# Full text of "ibm :: apl :: GC26-3847-0 APL Language Mar75"

## See other formats

GC26-3847-0 File No. S370-22 Systems APL Language FT 5 } PREFACE This manual is intended to provide a reference for the APL language, and also an introduction to APL to those unfamiliar with it. New users should read the introduction, which provides an overview of some fundamental concepts, and illustrates several kinds of use. Section 2 presents the fundamentals and introduces the terminology used in later sections, but the sections may otherwise be read relcitively independently. For example, a glance at the listing of the primitive functions in Figures 3.1 and 3.5 should suffice for the reader who wishes to concentrate just on the means of defining and using functions (programs) presented in Sections 6 and 7. Readers familiar with earlier versions of APL but not with the notions of shared variables, will find this topic and the related topics of system functions and system variables covered in Sections 4 and 5. The following publications are intended to supplement the information in this publication for particular APL systems: APL Shared Variables (APLSV) User's Guide, Order No. SH20-1460 APL/CMS User's Guide, Order No. SC20-1846 First Edition (March 1975) This publication serves two different APL systems: APL Shared Variables (Program Number 5799-AJF — Programming RPQ WE1191) and APL/CMS (Program Number 5799-ALK — Programming RPQ MF2608) . Changes may from time to time be made to the specifications herein; any such changes will be reported in subsequent revisions or Technical Newsletters. Before using this publication, consult the latest IBM System/360 and System/370 Bibliography , Order No. GA22-6822, for the editions that are applicable and current. Reqxiests for copies of IBM publications should be made to your IBM representative, or to the IBM branch office serving your locality. A form for readers ' comments is provided at the back of this publication. If the form has been removed, comments may be addressed to IBM Corporation Systems Development Division LDF Publishing — Department JO 4 1501 California Avenue Palo Alto, CA 94304. ©Copyright International Business Machines Corporation 1975 CONTENTS SECTION 1 : INTRODUCTION ..... 1 Two Examples of the Use of APL 1 An Isolated Calculation 1 A Prepared Workspace 2 The Characteristics of APL 7 SECTION 2: FUNDAMENTALS 9 Character Set 10 Scalar and Vector Constants ... 10 Spaces 13 Functions 13 Order of Execution 14 Arrays 14 Workspaces and Libraries 15 Names 16 User Identification 16 SECTION 3: PRIMITIVE FUNCTIONS AND OPERATORS 17 Scalar Functions 17 Plus, Minus, Times, Divide and Residue 19 Conjugate, Negative, Signum, Reciprocal and Magnitude 20 Boolean and Relational Functions 20 Minimum and Maximum 21 Floor and Ceiling 21 Roll (Random Number Function) 22 Power, Exponential, General and Natural Logarithm 22 Circular, Hyperbolic, and Pythagorean Functions 23 Factorial and Binomial Functions 24 Operators 25 Reduction 25 Scan 26 Axis 27 Inner Product 27 Outer Product '. 29 Mixed Functions 29 Structural Functions 31 Shape, Reshape, and Ravel 31 Reverse and Rotate 33 Catenate and Laminate 33 Transpose 35 Selection Functions 36 Take and Drop 36 Compress and Expand 36 Indexing 37 Selector Generators 38 Index Generator and Index of 38 Membership 39 Grade Functions 39 Deal 39 Numerical Functions . 40 Matrix Inverse and Matrix Divide 40 Decode and Encode 42 Data Transformations 43 Execute and Format 43 SECTION 4: SYSTEM FUNCTIONS AND SYSTEM VARIABLES 47 System Functions 47 Canonical Representation 47 Function Establishment .... 47 Expunge 48 Name List 49 Name Classification 49 Delay 49 System Variables 50 Contents iii SECTION 5: SHARED VARIABLES 52 Offers „ 52 Access Control . 55 Retraction 58 Inquiries 58 SECTION 6: FRICTION DEFINITION 59 Canonical Representation and Function Establishment ....... 59 The Function Header 60 Local and. Global Names 61 Branchincr and Statement Numbers 61 Labels 62 Comments 62 Function Ed.itina - the V Form 6 3 Addincr a Statement 63 Inserting or Replacina a Statement 6 3 Replacing the Header 63 Deleting a Statement 6 3 Editing a Statement or Header 6 4 Addina to a Statement or Header 6 4 Function Display 6 4 Leaving the V Form 65 SECTION 7: FRICTION EXECUTION 66 Halted Execution 66 State Indicator ......... 67 State Indicator Damage 68 Trace Control . 68 Stop Control 68 Locked Functions 69 Recursive Functions 69 Terminal Input and Output 70 Evaluated Input 71 Interrupting Evaluated Input ... 71 Character Input 71 Interrupting Character Input .... 71 Normal Output 72 Bare Output . 72 SECTION 8: SYSTEM COMMANDS .... 73 Commands that Modify the Workspace Environment .... 76 Grouping to Facilitate Copyina or Erasure .... 78 Commands that Monitor the Active Workspace .... 79 Commands for Workspace Storage and Retrieval ... 80 Libraries of Saved Workspaces .... 80 Names and Passwords for Workspaces 80 Automatic Savina after Line Drop •and Special Properties of the C OUT I HUE Workspace ....... 83 Commands Recrarding Workspace Storage and Retrieval ........ 83 Access to the System 83 Sign On 84 Sign Off 84 INDEX 87 iv APL Language ILLUSTRATIONS Figure Title Paae Figure 1. ,1 Figure 2. ,1 Figure 2. .2 Figure 2, .3 Figure 3, .1 Figure 3. ,2 Fiaure 3. ,3 Figure 3. ,4 Figure 3. ,5 Figure 3. ,6 Figure 3. ,7 Figure 4, .1 Figure 4. ,2 Figure 5, .1 Figure 5, .2 Figure 5, ,3 Figure 8, .1 Figure 8, ,2 Figure 8. .3 Functions for Sales, Billina, and Inventory Control ... 6 Error Reports 11 The APL Character Set 12 Typical APL Keyboard ......... 12 Primitive Scalar Functions 18 Identity Elements of Primitive Scalar Dyadic Functions . 19 The Pythagorean Functions 2 4 Inner Product 28 Primitive fixed Functions 30 Scalar-Vector Substitutions for fixed Functions .... 31 Shape and Rank Vectors 32 System Functions 48 System Variables 51 Functions for the Management of Sharing 5 3 Access Control of a Shared Variable 56 Some Useful Settings for the Access Control Vector ... 57 System Commands 7 4 Trouble Reports 75 Environment Within a Clear Workspace 76 Illustrations SECTION 1 ; INTRODUCTION APL is a general-purpose language which enjoys extensive use in such diverse applications as commercial data processing, system design, mathematical and scientific computation, and the teaching of mathematics and other subjects. It has proved particularly useful in data-base applications, where its computational power and communication facilities combine to enhance the productivity of both application programmers and end users. When implemented as a computing system, APL is used from a typewriter-like keyboard. Statements that specify the work to be done are entered by typing them, and in response the computer displays the result of the computation. The result appears at a device which accompanies the keyboard, such as a printer, or video display. In addition to work purely at the keyboard and its associated display, entries may also invoke the use of printers, disk-files, tapes or other remote devices . TWO EXAMPLES OF THE USE OF APL A statement entered at the keyboard may contain numbers , or symbols such as + - x *, or names formed from letters of the alphabet. The numbers and special symbols stand for the primitive objects and functions of APL; primitive in the sense that their meanings are permanently fixed, and therefore understood by the APL system without further definition. A name, however, has no significance until a meaning has been assigned to it. Names are used for two major categories of objects. There are names for collections of data, made up of numbers or characters. Such a named collection is. called a variable . Names may also be used for programs made up of sequences of APL statements. Such programs are called defined functions . Once they have been established, names of variables and defined functions can be used in statements by themselves or in combination with the primitive functions and objects. AN ISOLATED CALCULATION If the work to be done can be adequately specified simply by keying a statement made up of numbers and symbols, names will not be required: entering the expression to be evaluated causes the result to be displayed. For example, suppose it is required to compare the rates of return on money at a fixed interest rate but with different compounding intervals. For 1000 units at 6%, compounded annually, quarterly, monthly, or daily, for 10 years, the transaction (at a typewriter terminal) would look like this: 1000x(l+. 06*1 4 12 365)*10xl 4 12 365 (entry) 1790.85 1814.02 1819.4 1822.03 (response) (The largest gain is apparently obtained in going from annually to quarterly, and after that the differences are relatively insignificant.) Several distinctive features of APL are illustrated in this example: familiar symbols such as + x * are used where possible; symbols are introduced where necessary, (as the * for the power function) ; and a group of numbers can be worked on together. Section 1 : Introduction A PREPARED WORKSPACE Although there are many problems that can be solved by keying in the appropriate numbers and symbols, the greatest benefits of using APL come when named functions and data are used. Since a single name may refer to a large array of data, using the name is far simpler than keying in all of its members. Similarly, a defined function, invoked by entering its name , may be composed of many individual APL statements that, would be burdensome to type individually again and again. Once a function has been defined, or data collected under a name, it is usually desirable to retain the significance of the names for some period of time; perhaps for just a few minutes, but more often for much longer periods, possibly months or years. For this reason APL systems are organized around the concept of a workspace , which might be thought of as a notebook in which all the different items needed during some piece of work are recorded together. The following example illustrates the use of an application package - a workspace prepared for a particular data-processing application. It is not expected that the reader new to APL will immediately follow all details, but the example should nevertheless provide, on the one hand, an indication of the ease of exploring and using such a package, and on the other hand, the relative ease of constructing it. The example is a skeletal system for sales, billing, and inventory control for, say, a wholesale distributor of gadgets. The system maintains an inventory of items in stock, with part numbers, descriptions, unit prices, quantities on hand, and reorder levels. It automatically adjusts the quantity on hand when an invoice is prepared, and signals when the stock level goes below the reorder level. It also provides for entering new stock items in the inventory list and has provision for order entry and printing of invoices. To complete this basic system for actual application, it would be necessary to add functions such as the recording of a journal and the maintenance of the customer list, and to add appropriate checks on errors of input and on security. Nevertheless, the package does work, as far as it goes, and in addition to showing the use of many functions of the language, also demonstrates the conciseness of APL programming. To start, the stored workspace containing the application package is activated, using a system command : )LOAD 1 SBIC SAVED 18.42.25 02/06/75 To become acquainted with the contents of the package the names of variables and defined functions are listed: )VARS CUSTLIST DESCRIBE INVNO LOW MTH ORDLIST STOCKLIST )FNS ADDRESS DATE GET INVOICE NEWSTOCK ORDER ORDERENTRI PRINT PUT RESTOCK APL Language The variable name DESCRIBE is suggestive. Its value can be displayed by simply entering the name: DESCRIBE THIS WORKSPACE CONTAINS FUNCTIONS FOR RECORDING ORDERS, MAINTAINING AN INVENTORY, AND PREPARING INVOICES. IT IS A SKELETAL SYSTEM DESIGNED TO ILLUSTRATE THE USE OF APL IN COMMERCIAL DATA PROCESSING. THE VARIABLES CUSTLIST , ORDLIST , AND STOCKLIST CARRY, RESPECTIVELY , CUSTOMER NAMES AND ADDRESSES KEYED TO A CUSTOMER NUMBER, ORDERS BY STOCK NUMBER AND CUSTOMER NUMBER, AND THE INVENTORY LIST OF STOCK ITEMS. INVNO IS A COUNTER FOR SUCCESSIVE INVOICE NUMBERS, LOW INDICATES ITEMS TO BE REORDERED, AND MTH HOLDS NAMES FOR MONTHS OF THE YEAR. WHEN DISPLAYING THE STOCK LIST OR CUSTOMER LIST ON A TYPEWRITER TERMINAL IT WILL BE DESIRABLE TO CHANGE TO A TYPE-ELEMENT HAVING BOTH UPPER AND LOWER CASE ALPHABETS. MEANINGFUL STATEMENTS IN THIS WORKSPACE ARE: NEWSTOCK ORDERENTRY PRINT INVOICE ORDER N RESTOCK WHERE N IS A CUSTOMER NUMBER. FOR CONSISTENCY WITH THE DATA ALREADY ENTERED, NEWSTOCK AND PRINT SHOULD ALSO BE USED WITH A TYPE-ELEMENT THAT HAS BOTH ALPHABETS. THE FUNCTIONS ADDRESS, DATE, GET, AND PUT ARE NOT NORMALLY INVOKED BY A DIRECT KEYBOARD ENTRY, BUT ARE USED BY THE VARIOUS FUNCTIONS NOTED ABOVE. It might be helpful at this point to display STOCKLIST to see just what the information looks like. But the list might be very large, and it is good practice to find out its size before asking for the display: pSTOCKLIST 6 39 The list has 6 rows and 39 columns, which is not too much to display in its entirety. Following the advice in DESCRIBE the type-element can be changed and the variable name entered: stocklist 1135 First Great Item 9993 High Flyer Widget 3569 Second Moneymaker 5613 Mail Order Special 2583 A Real Winner 9998 Nonesuch Frammis Next it might be useful to look at the customer list: pCUSTLIST 3 5 20 9.95 350 55 88.73 240 35 24.75 200 30 14.99 600 95 49.99 125 10 2.69 500 50 Section 1 : Introduction The customer list is apparently represented by a three-dimensional array, and it will be interesting to see how it is displayed: custlist 7 City Traders Inc. 41 Postage Road Rimela, N. Y. 12345 55 Mail House Ltd. 7-11 Ramblers Lane Offshore island City, S. Dak. 54321 312 Mantup Sales Corp. Ruralia Farms RFD 2 Suburbian, Wis. 0000 Finally, it is probably worth looking at the order list: pORDLIST 6 3 ORDLIST 55 3569 5 312 9998 12 7 1135 2 312 3569 10 312 5613 45 7 5613 75 This is a 3-column numerical array, and the significance of each column is easily deduced from the previous displays: the sucessive columns appear to represent customer number, stock number, and quantity. Use of the package can be demonstrated by trying the meaningful statements : ORDERENTRY CUSTOMER ITEM QUANTITY In response to the statement ORDERENTRY the system has displayed column headings, and the keyboard has unlocked for further entry. These can be supplied, using some of the existing customer and item numbers. The entire transaction at the terminal might be this : ORDERENTRY CUSTOMER ITEM QUANTITY 55 1135 12 312 1135 24 55 2583 4 Since customer 5 5 had one item on order before, three should be on order now. APL Language Although it is not listed as a meaningful statement, what happens if the function ORDER is used by itself? ORDER 5 5 55 3569 5 55 1135 12 55 2583 4 This entrv produces a result which seems to confirm the number of items on "rderf It turns out that this result will be used by INVOICE to produce a result which will in turn be used by PRINT. invoice order 55 1336 3569 Second Moneymaker 1 1 35 First Great Item 2583 A Real Winner If the complete statement given in DESCRIBE is entered rather then these piecemeal entries, the result is a formatted output xntended to be used with a pre-printed form: print invoice order 55 55 24.75 5 123.75 9.95 12 119.40 49.99 4 199.96 To: Mail House Ltd. 7-11 Ramblers Lane Offshore Island City, S. Dak. 54321 Invoice No. 1336 Feb 8, 1975 Stock 3569 1135 2583 Description Second Moneymaker First Great Item A Real Winner Price 24.75 9.95 49.99 Quan. 5 12 4 Exten. 123.75 119.40 199.96 Total $ 443.11 Distributors Corp. 123 First Ave., City, St. 99999 For the sake of completeness, and because they illustrate variations in the method of requesting input, the remaining two statements can be entered. NEWSTOCK prints a prompting message and then unlocks the keyboard, waiting for entry of the response on the same line: newstock stock number/ 8760 description/ The Best Gadget unit price/ 1.73 initial inventory/ 875 reorder level/ 100 RESTOCK not only prints a prompting message, but uses an additional prompt D: supplied by the system: RESTOCK STOCK NUMBER D: 1135 STOCK INCREMENT D: 30 Section 1 : Introduction 9 95 368 55 88 73 240 35 24 75 195 30 14 99 600 95 49 99 121 10 2. 69 500 50 It might now be of interest to display the inventory once more to see the effect of the previous operations: stocklist 1135 First Great Item 9993 High Flyer Widget 3569 Second Moneymaker 5613 Mail Order Special 2583 A Real Winner 999 8 Nonesuch Frammis 8760 The Best Gadget 1.73 875 100 The quantities on hand do indeed show the effect of completing the order, replenishing the stock, and adding a new item. The complete set of ten functions in this package is displayed in Figure 1.1. The first line in each definition is the function head er, which specifies, among other things, the function name and syntax"! — The remainder in each individual display is the function body . The longest function, INVOICE, has twelve lines, the shortest, ORDER, has only one. FORM-SPRINT N;T;X X+l+pN F0RM<r~H<b 12 43 +ADDRESS 1 ~6 +W F0flM[l;37+i6>6+ff[l; ] FORMl3;31+\12]+DATE QTS F0RMi5+xX-l;l«- 1 +ff F0RML12; ]-<-~43 + T + /i , 1 35 IN 1]) Z+INVOICE N;R;X;PQR;EXT X+ 6 VlNVNO+INVNO+1 Z+ 1 43 p(X, 37 TtfCl; PQR+&.251R+GET J[2] EXT-rXL3lxPQRH] 2*Z,[l3(31+i?), 4 8 2 ?Xl3l,EXT PQRL21+PQR121-X131 ■+(>/PQRL2 3])/£2 L0W+L0WA~Xl2leL0W) /XZ21 £2:fl[31+i4]-e 4 fPQi?[2] R PUT ATC 2] -»-(0*l + pilM- 1 +ff)/Ll Z+ORDER N Z«-( ORDLISTl -,U=N) /ORDLIST Z+ADDRESS Nil J> ( CUSTLISTl ;l;i6]A. = ,tf)il Z«- 1 ICUSTLISTH; ;] Z+DATE N Z+-MTHlNL2l;l, 3 6 «[3 1] Z[7>»,» NEWSTOCKiR EH-' STOCK NUMBER/ • R+ 4 Tid CD-*-' DESCRIPTION/ ' i?-«-fl,21 + 12 + [Il ek ' wit price/ ' i?+-i?, 6 2 TIB PH-'JffJ2\ZVl£ INVENTORY/ R+R, 4 t±H EH-' REORDER LEVEL/ ' fl«-fl, 4 TiE i? PUTsl^*R ORDERENTRI ; L ' CUSTOMER ITEM QUANTITY* LI :-►( ' 'A. =L-f-[3)/0 <** - ORDLIST+ORDLIST,tlli.L ■+L1 RESTOCK;R;X;PQR < STOCK NUMBER' PQR<r±25iR+GET X<-Q ' STOCK INCREMENT' i?[31 + i4]«- 4 VPQRL21+PQR121+Q R PUT X R PUT Nil I+{STOCKLIST\_ ;i4]a.= 4 wN)\l + (.I*l + pSTOCKLIST)/Ll STOCKLIST+STOCKLIST. Ill ' ' L1-.ST0CKLISTLI; >i? Z-<-0£T #;I If-(52 , 0CXLJ52'C;i4]A.= 4 Ti7) 1 1 Z+STOCKLISTHil Figure 1.1: Functions for Sales, Billing, and Inventory Control APL Language The details of the programming will not be discussed here, but one point is worth noting. As they stand here the various data lists are very small. In a real use, one or more of them might have many thousands of entries. A good way to handle them in that case is illustrated by the treatment of STOCKLIST, which is accessed only by the functions put and GET, rather than the primitive APL functions which could have been used directly for this purpose. By thus isolating the access functions the application package design is automatically made more general; if a different representation were chosen for STOCKLIST - say, an external file- the required changes in the programming would be confined to the definitions of PUT and GET, and the other functions such as INVOICE or NEWSTOCK, which give the package its particular character, would be unaffected. In this way, .an APL application can be expanded to data-bases of arbitrary size, well beyond the storage capacity of the workspace that establishes the environment for the work. THE CHARACTERISTICS OF APL The subsequent sections of this manual describe APL in detail, giving the meaning of each symbol and discussing the various features common to the APL systems currently available from IBM. It is well to view these, details in light of the major characteristics of APL, which may be summarized as follows: The primitive objects of the language are arrays (lists, tables, lists of tables, etc.). For example, A+B is meaningful for any arrays A and B, the size of an array \pA) is a primitive function, and arrays may be indexed by arrays, as in yl[3 l 4- 2] The syntax is simple: there are only three statement types (name assignment, branch, or neither) , there is no function precedence hierarchy, functions have either one, two, or no arguments, and primitive functions and defined functions (programs) are treated alike. The semantic rules are few: the definitions of primitive functions are independent of the representations of data to which they apply, all scalar functions are extended to other arrays in the same way (that is, item-by-item) , and primitive functions have no hidden effects (so-called side-effects) . The sequence control is simple: one statement type embraces all types of branches (conditional, unconditional, computed, etc.), and the termination of the execution of any function always returns control to the point of use. External communication is established by means of variables which are shared between APL and other systems or subsystems. These shared variables are treated both syntactically and semantically like other variables. A subclass of shared variables, system variables , provides convenient communication between APL programs and their environment. The utility of the primitive functions is vastly enhanced by operators which modify their behavior in a systematic manner. For example, reduction (denoted by /) modifies a function to apply over all elements of a list, as in +/L for summation of the items of £. The remaining operators are scan (running totals, running maxima, etc.), the axis operator which, for example, allows reduction and scan to be applied over a specified axis (rows or columns) of a table, the outer product , which produces tables of values as in RATE" ,*YEARS for an interest table, and the inner product , a simple generalization of matrix product which is exceedingly useful in data processing and other non-mathematical applications. Section 1 : Introduction 7 The number of primitive functions is small enough that each is represented by a single easily-read and easily-written symbol, yet the set of primitives embraces operations from simple addition to grading (sorting) and formatting. The complete set can be classified as follows: Arithmetic : + -xt*«o|L["!S Boolean and Relational : vava~<<; = 2:>* Selection and Structural: /\j<\[;] + + p,4>$e General: e\?iT^iiv 8 APL Language SECTION 2; FUNDAMENTALS A typical statement in APL is of the form: AREA-*-?,*** The effect of the statement is to assign to the name AREA the value of the expression 3x4 to the right of the specification arrow «- ; the statement may be read informally as "AREA i£ three times four." The statement is the normal unit of execution. Two primitive types occur, the specification illustrated above, and the branch , which serves to control the sequence in which the statements in a defined function (discussed in Section 6) are executed. There is also a third type of statement which may invoke the use of a defined function without either a specification or a branch. A variant of the specification statement produces display of a result on the medium (paper or screen) provided by the terminal device; if the leftmost part of a statement is not a name followed by a specification, the result of the expression is displayed. For example: 12 14 3x4 PERIMETER*-2x(3 + H) PERIMETER Printing of the result of any part of a statement can be obtained by including the characters Q+ at the appropriate point in the statement. Moreover, any number of specification arrows may occur in a statement. For example: 12 14 4 Xf-2+D-*-3xY-<-4 X Y The terminal entry and display devices used with APL systems include a variety of typewriter-like and display-tube devices. Their characteristics vary, but the essential common characteristics are: 1. The ability to enter and display APL characters. 2. A means of signalling completion (and release to the system) of an entry. 3. Facilities for convenient revision of an entry before release. 4. Facilities to interrupt execution at the end of a statement ( weak interrupt ) and within a statement ( strong interrupt ) . 5. A cursor , such as an arrowhead, to show where on the line the next character entered will appear. All examples in this manual are presented as produced on a typewriter-like device on which the release signal is produced by the carrier return key, and revision is handled by backspacing to the point of revision, striking the attention button, and entering the revision. A caret supplied by the system marks the point of correction. For Section 2 : Fundamentals example : 18 3+4x5+ A + 5 + 6 On terminals of this type the attention key is also used for interrupting execution. A single strike of this key while execution is in progress provides a weak interrupt, and a double strike provides a strong interrupt. Entry of a statement which cannot be executed will invoke an error re P ort . which indicates the nature of the error and the point at which execution stopped. For example: Z-f-5 3+(YxX ) VALUE ERROR 3+(7xZ) A Error messages are listed in Figure 2.1, together with information on the cause and suggested corrective action. CHARACTER SET The characters which may occur in a statement fall in four main classes: alphabetic, numeric, special, and blank. The alphabetics comprise the roman alphabet in upper case italic font, and the same alphabet underscored. The entire set is shown in Figure 2.2 together with suggested names and the scheme for forming (as composites of other symbols) those which may not be directly available on the keys of certain terminal devices. A typical keyboard layout is shown in Figure The names suggested are for the symbols themselves and not necessarily for the functions they represent. For example, the downstile L represents both the minimum , a function of two arguments, and the floor (or integer part ) , a function of one argument. In general, most of the special characters (such as +, -, x, and *) are used to denote primitive functions which are assigned fixed meanings, and the alphabetic characters are used to form names which may be assigned and re-assigned significance as variables, defined functions, and other objects. The blank serves as a separator to mark divisions between names (which are of arbitrary length) . For terminal devices which permit the display font to be changed without changing the behavior of the entry keyboard or communication with the system (as in changing the typing element on certain typewriters), any available display font may be used. For example, in textual work a font with normal upper- and lower-case roman is commonly employed. SCALAR AND VECTOR CONSTANTS All numbers entered or displayed are in decimal, either in conventional form (including a decimal point if appropriate) or in scaled form. The scaled form consists of an integer or decimal fraction callesd the multiplier followed immediately by the symbol E followed immediately by an integer (which must not include a decimal point) called the scale . The scale specifies the power of ten by which the multiplier is to be multiplied. Thus l . 44E2 is equivalent to 144. 1 APL Language TYPE CHARACTER DOMAIN DEFN Q— IMPLICIT INDEX INTERFACE QUOTA EXHAUSTED INTERRUPT LENGTH NO SHARES RANK RESEND SI DAMAGE SYNTAX SYMBOL TABLE FULL SYSTEM VALUE WS FULL Cause; CORRECTIVE ACTION Illegitimate overstrike. Arguments not in the domain of the function. Misuse of V or Q symbols: 1. The function is pendent. DISPLAY STATE INDICATOR AND CLEAR AS REQUIRED. 2 . Use of other than the function name alone in reopening a definition. 3. Improper request for a line edit or display. The system variable D — ( for example, 010) has been set to an inappropriate value. Index value out of range. Attempt to share more variables than allotted quota. REQUEST LARGER QUOTA FROM APL OPERATOR. Execution was suspended within an APL statement. TO RESUME EXECUTION, ENTER A BRANCH TO THE STATEMENT INTERRUPTED. Shapes not conformable. Shared variable facility not in operation. Ranks not conformable. Transmission failure or more than the implementation-allowed number of characters entered in one line. RE-ENTER. IF CHRONIC, REDIAL OR HAVE TERMINAL OR PHONE REPAIRED. The state indicator (an internal list of suspended and pendent functions) has been damaged in editing a function or in performing a )COPY or ) ERASE. Invalid syntax; e.g. two variables juxtaposed; function used without appropriate arguments as dictated by its header; unmatched parentheses. Too many names used. SAVE, CLEAR, COPY or SAVE, CLEAR, SYMBOLS, COPY or ERASE, SAVE, CLEAR, COPY Fault in internal operation of the system. RELOAD. SEND TYPED RECORD, INCLUDING ALL WORK LEADING TO THE ERROR, TO THE SYSTEM MANAGER. Use of name which has not been assigned a value. A VALUE TO THE VARIABLE, OR DEFINE THE FUNCTION. ASSIGN Workspace is filled (perhaps by temporary values produced in evaluating a compound expression, or by values of Shared variables) . CLEAR STATE INDICATOR, ERASE NEEDLESS OBJECTS, OR REVISE CALCULATIONS TO USE LESS SPACE. Figure 2.1: Error Reports Section 2 : Fundamentals 11 A B C D E F G H I J KLMNOPQR S T U V W X I Z A B C D E F G H I I KLMNQPQR S nznn 1 2 3 4 5 6 7 8 9 •• dieresis alpha V nor n+t V overbar r upstile H nand ~ A < less L downstile f del stile V | < not greater underbar 4 delta stile A I = equal V del 4> circle stile O I > not less A delta * circle slope o \ > greater null e circle bar o * not equal t quote ® log o * V or u quad i I-beam 1 T A and ( open paren ¥ del tilde V ~ - bar ) close paren 4 base null JL T divide c open bracket f top null T o + plus ] close bracket \ slope bar \ - X times c open shoe / slash bar / - J> query 3 close shoe fi cap null n u omega n cap 13 quote quad r D e epsilon u cup j quote dot t , P rho i base B domino n ♦. ~ tilde T top + up (arrow) 1 stile + down (arrow) 9 semicolon i iota : colon o circle » comma * star , dot ■+• right (arrow) \ slope ■*- left (arrow) / slash space Figure 2.2: The APL Character Set uu. < 3 < 4 5 > 6 > 7 8 V 9 A o + • • X BACK SPACE -II 5 — — y— (A) w P R T t Y I I O o * P .-► v RETURN L oc7^[a r s L D F V A H e J i K D L ( E ) ] SHIFT c z n c U V ± T 1 M • • * • \ / SHIFT j Figure 2.3: Typical APL Keyboard 12 APL Language Negative numbers are represented by an overbar immediately preceding the number, for example, "1.44 and 144E 2 are equivalent negative numbers. The overbar can be used only as part of a constant and is to be distinguished from the bar which denotes negation, as in -X. A single numerical constant entered by itself is accepted by the system as a scalar . A constant vector may be entered by listing the numerical components in order, separated by one or more spaces. A scalar character constant may be entered by placing the character between quotation marks, and a character vector may be entered by listing the characters between quotation marks. Such a vector is displayed by the system as the sequence of characters, with no enclosing quotes and with no separation of the successive elements. The quote character itself must be entered as a pair of quotes. Thus, the abbreviation of CANNOT is entered as x CAN xx T r and prints as CAN'T. SPACES The blank character is used primarily as a separator. The spaces that one or more blank characters produce are needed to separate names of adjacent defined functions, constants, and variables. For example, if F is a defined function, then the expression 3 F 4 must be entered with the indicated spaces. The exact number of spaces used in succession is of no importance, and extra spaces may be used freely. Spaces are not required between primitive functions and constants or variables, or between a succession of primitive functions, but they may be used if desired. For example, the expression 3+4 may be entered with no spaces. FUNCTIONS The word "function" derives from a word which means to execute or to perform. A function executes some action on its argument (or arguments) to produce a result which may serve as an argument to another function. For example: ~ ~" 12 14 "2 3x4 2+(3x4) (-6)t3 A function (such as the negation used above) which takes one argument is said to be monadic , and a function (such as times ) which takes two arguments is said to be dyadic . All APL functions are either monadic or dyadic or, in the case of defined functions only, niladic (taking no argument) . Certain of the special symbols are used to denote two different functions, one monadic and the other dyadic. For example, X-Y denotes s ubtraction of Y from X (a dyadic function) , and -Y denotes negation of I (a monadic function) . Other examples appear in Figures 3 . 1 and 3.5. Each of the primitive functions is denoted by a single character or by an operator (discussed in Section 3) applied to such a character. For example, + and * are primitive functions as are +/ and * / (since / denotes an operator) . Section 2 : Fundamentals 1 3 ORDER OF EXECUTION Parentheses are used in the familiar way to control the order of execution in a statement. Any expression within matching parentheses is evaluated before applying to the result any function outside the matching pair. In conventional notation, the order of execution of an unparenthesized sequence of monadic functions may be stated as follows: the (right-hand) argument of any function is the value of the entire expression to the right. For example, Log Sin Arctan x means the Log of Sin Arctan x, which means Log of Sin of Arctan x. In APL, the same rule applies to dyadic functions as well. Moreover, all functions, both primitive and defined, are treated alike; there is no hierarchy among functions (such as multiplication being done before addition or subtraction) . An equivalent statement of this rule is that an unparenthesized expression is evaluated in order from right to left. For example, the expression 3x8T3*|5-7 is equivalent to 3x(8["(3*(l(5-7)))). Their result is 27. A consequence of the rule is that the only substantive use of parentheses is to form the left argument of a function. For example, (12t3)x2 is 8 and 12*3*2 is 2. However, redundant pairs of parentheses can be used at will. Thus, 12* (3*2) is also 2. ARRAYS APL functions apply to collections of individual items called arrays . Arrays range from scalars, which are dimensionless, to multi-dimensional arrays of arbitrary rank and size. The vector is a simple form of array which may be formed by listing its elements as described in the discussion of constants. For example: V+2 35711131719 A+ X ABCDEFGR X The elements of a vector may be selected by indexing . For example: F[3 1 5] 5 2 11 AlQ 5 14] HEAD Arrays of more complex structure may be formed with the reshape function denoted by p: M<-2 4p7 S+-2 UpA M B 2 3 5 7 ABCD 11 13 17 19 EFGH These results have two dimensions or axes and are called t able s or matrices . A matrix has two axes "and is said to be of rank 2 ; a vector has one axis and is of rank 1 . The left argument 2 4 in the foregoing examples specifies the shape of the resulting array. Arrays of arbitrary shape and rank may be 1 >i APL Language produced by the same scheme. For example: T+2 3 Hp'ABCDEFGHIJKLMNOPQRSTUVWX x T ABCD EFGE IJKL MNOP QRST UVWX The shape of an array can be determined by the monadic function denoted by p : p7 pA? pT 8 2 4 2 3 4 Elements may be selected from any array (other than a scalar) by indexing in the manner shown for vectors, except that indices must be provided for each axis: M[2;3] T[2;l;4] 17 P Ml 2 1;2 3 4] Tl2;l 2 3;1 2 3 4] 13 17 19 MNOP 3 5 7 QRST U7WX The indexing used in the foregoing examples is called 1 - origin because the first element along each axis is selected by the index i . One may also use o-origin indexing by setting the index v origin to o. The index origin is a system variable (See Section 4) denoted by 010. Thus: QI0+1 UIO+-0 711 2 3] y[0 1 2] 2 3 5 2 3 5 3[2;3] B[l;2] G G All further examples assume i-origin unless otherwise stated. WORKSPACES AND LIBRARIES The common organizational unit in an APL system is the workspace . When in use, a workspace is said to be active , and it occupies a block of working storage in the central computer. Part of each workspace is set aside to serve the internal workings of the system, and the remainder is used, as required, for storing items of information and for containing transient information generated in the course of a computation. An active workspace is always associated with a terminal during a work session, and all transactions with the system are mediated by it. In particular, the names of variables (data items) and defined functions (programs) used in calculations always refer to objects known by those names in the active workspace; information on the progress of program execution is maintained in the state indicator of the active workspace; and control information affecting the form of output is held within the active workspace. Section 2 : Fundamentals 1 5 Inactive workspaces are stored in libraries , where they are identified by arbitrary names. They occupy space in secondary storage facilities of the central computer and cannot be worked with directly. When required, copies of stored workspaces can be made active, or selected information may be copied from them into an active workspace. Libraries are either private or public . Private libraries are associated with individual users of the system, and are identified by the user's account number. Access to them by other users is restricted in that one user may not store workspaces in another person's library, nor obtain a listing of the workspaces already stored there. However, one user may activate a copy of another user's unlocked workspace if he knows the library number and workspace name. Workspaces and libraries are managed by system commands as described in Section 8 . NAMES Names of workspaces, functions, variables, and groups (see Section 8) may be formed of any sequence of alphabetic and numeric characters that starts with an alphabetic and contains no blank. The environment in which APL operations take place is bounded by the active workspace. Hence, the same name may be used to designate different objects (that is, groups, functions, or variables) in different workspaces, without interference. Also, since workspaces themselves are never the subject of APL operations, but only of system commands, it is possible for a workspace to have the same name as an object it holds. Stored workspaces and the information they hold can be protected against unauthorized use by associating a lock , comprising a colon and a password of the user's choice, with the name of the workspace, when the workspace is stored. In order to activate a locked workspace or copy any information it contains, a colon and the password must again be used, as a key , in conjunction with the workspace name. Listings of workspace names, including those in public libraries, never give the keys, and do not overtly indicate the existence of a lock. USER IDENTIFICATION Account numbers can be similarly protected by locks and keys, thus maintaining the security of a user's private library and avoiding unauthorized charges against his account. Passwords for locks and keys may be formed of any sequence of alphabetic and numeric characters . In use as either a lock or key, a password follows the number or name it is protecting, from which it is set off by a colon. APL systems differ in the procedure required to sign-on or begin a session. However, a numerical identification of the user is usually provided in some manner, so that it can be used to specify the first element of DAI. 16 APL Language SECTION 3: PRIMITIVE FUNCTIONS AND OPERATORS The primitive functions fall in two classes, scalar , and mixed . Scalar functions are defined on scalar arguments and are extended to other arrays item-by-item. Mixed functions are defined on arrays of various ranks and may yield results which differ from the arguments in both rank and shape. Five primitive operators apply to scalar dyadic functions and to certain mixed functions to produce a large number of new functions. The definitions of certain functions depend on certain system variables whose names begin with the symbol Q (as in QIO and UCT) . These system variables are discussed further in Section 4. SCALAR FUNCTIONS A monadic scalar function extends to each item of an array argument; the result is an array of the same shape as the argument and each item of the result is obtained as the monadic function applied to the corresponding item of the argument. A dyadic scalar function extends similarly to a pair of arguments of the same shape. To be conformable, the arguments must agree in shape, or at least one of them must be a scalar or one-element vector. If one of the arguments has only one item, that item is applied in determining each element of the result. For example: 1 2 3x4 5 6 4 10 18 3 + U 5 6 7 8 9 2 3+4 5 6 LENGTH ERROR Each of the scalar functions is defined on all real numbers with two general exceptions: the four boolean functions are defined only on the numbers o and l, and the functions = and * are defined on characters as well as numbers. Specific exceptions (such as 4-fO) will be noted where appropriate . The scalar functions are summarized in Figure 3.1 together with their symbols and brief definitions or examples which should make their use clear. The remainder of this section is devoted to more detailed definitions. A dyadic function f may possess a left identity element L such that L f X equals X for any J, or a right identity element R such that X f R equals X. For example, one is a right identity element of * since XtI is X, zero is a left or right identity of +, one is a left or right identity of x , and the general logarithm function ® has no identity element. Identity elements become important as the appropriate result of applying a function over an empty vector; for example, the sum over an empty vector is 0, (the identity element of +) , and the product over an empty vector is 1, the identity element of x. These matters are discussed further in the treatment of the reduction operator which concerns such applications of dyadic functions over vectors. Figure 3.2 lists the identity elements of the dyadic scalar functions. The relational functions <, £, =, £, > and * possess no true identity elements, but do when considered as boolean functions, that is, i Section 3 : Primitive Functions and Operators 1 7 Monadic form ffl Dyadic form AfB Definition or example Name Name Definition or example +B IS B -B is 0-B xB is (B>0)-B<0 *B is ltB |~3.14 is 3 .14 B LB rs 3. 14 "3.14 3 ~4 4 "3 ?B is Random choice from iB *B is (2 .71828. . )*B »*N is W is *«N OB is Bx3 . 14159 . . . !0 is 1 !B is Bx!B-l or IB is Gamma (B+l) "1 is '0 is l Conjugate Negative Signum Reciprocal Magnitude Floor Ceiling Roll Exponential Natural logarithm Pi times Factorial Not {-A)QB A 4 OB (1-B*2)* . 5 (1-3*2)*. 5 Arcs in B 1 Sine B Arccos B 2 Cosine B Arctan B 3 Tangent B ("l+B*2)*.5 4 (1+B*2)*.5 Arsinh B 5 Sinh B Arcosh B 6 Cosh B Artanh B 7 Tanh B Table of Dyadic o Functions Plus Minus Times Divide Residue Minimum Maximum Deal Power General logarithm 2+3. 2 IS 5.2 2-3 .2 is "1.2 2x3.2 is 6.4 2*3 . 2 is .625 A \B is B-A-*LB*A+A = 3L7 is 3 3T7 is 7 A Mixed Function (See Figure 3.5) 2*3 is 8 A»B is Log B base A A®B is (&B)t®A Circular, Hyperbolic, Pythagorean (See table at left) Binomial And Or Nand Nor Less Not greater Equal Not less Greater Not Equal A\B is (!B)*(!i4)x!B-i4 2!5 is 10 3!5 is 10 AVB A B AAB AVB A«B 1 1 1 1 1 1 1 1 1 1 1 Relations Result is 1 if the relation holds , if it does not: 3<7 is 1 7<3 is Figure 3.1: Primitive Scalar Functions 1 8 APL Language when restricted to the domain included in the figure. and i. These identity elements are Dyadic Identity Left- Function Element Right Plus < L R Minus - R Times X 1 L R Divide ■f 1 R Residue 1 L Minimum L (note 1 ) L R Maximum r (note 2) L R Power * 1 R Logarithm ® None Circle o None Binomial 1 1 L And A 1 L R Or V L R Nand i\ None Nor ¥ None Less < \ Apply L Not greater < 1 I for L Equal = 1 \ boolean L R Not less > l ( arguments R Greater > \ only R Not equal £ o) L R Note 1 : the largest representable number Note 2 : the greatest in magnitude of representable negative numbers Figure 3.2: Identity Elements of Primitive Scalar Dyadic Functions PLUS, MINUS, TIMES, DIVIDE AND RESIDUE The definitions of the first four of these functions agree with the familiar definitions except that the indeterminate case 0*0 is defined to yield the value 1. For X*o , the expression ;sr*0 evokes a domain error. If A and B are positive integers, then the residue A\B is the remainder on dividing A into B. The following definition covers all values of A and B: If A=0 , then A\B equals B If A*Q, then A\B lies between A and zero (being permitted to equal zero but not A) and is equal to B-N*A for some integer N. For example: 1| 2.385 I 5, 0.385 5.8 12 3 I 3 2 10123 "1 ~2 "1 3|~3 "2 "1 1 2 3 12 Section 3 : Primative Functions and Operators 1 9 CONJUGATE, NEGATIVE, SIGNUM, RECIPROCAL, MAGNITUDE The conjugate function +x yields its argument unchanged, the negative function -X yields the argument reversed in sign, and the reciprocal *X is equivalent to nx. For example, if x«-4 ""5, then: +X -X iX 4-5 "4 5 0.25 "0.2 The result of the sign urn function *x depends on the sign of its argument, being "1 if x<0 , and if 1=0, and l if x>0. The magnitude function \X (also called absolute value ) yields the greater of X and -X; in terms of the signum function it is equivalent to XxxX. For example: x~3 4 |"3 4 10 1 3 4 BOOLEAN AND RELATIONAL FUNCTIONS The boolean functions and , or , nand (not-and) , and nor (not-or) apply only to boolean arguments, that is, and 1; if is interpreted as false , and 1 as true , then the definitions of these functions are evident from their "names. For example, ,4 AS (read as A and B) equals 1 (is true ) only if A equals 1 (is true ) and B equals 1. All cases are covered by the following examples: A+0 Oil fl+0 10 1 A*B avB A*B A*B 0001 0111 1110 1000 The monadic function not yields the logical complement of its argument, that is ~0 is 1, and ~l is 0. The relational functions apply to any numbers, but yield only boolean results, that is or 1. The result is l if the indicated relation holds, and otherwise. For example: 3 5<5 3 3 5 7*7 5 3 10 10 1 The comparisons involved in determining the results of the relational functions are not absolute, but are made to a certain tolerance specified by the comparison tolerance OCT. Two scalar quantities A and B are considered to be equal if the magnitude of their difference does not exceed the value of UCT multiplied by the larger of the magnitudes of A and B, that is, if (\A-B) is less than or equal to Uct*{ u>r |s. Similarly, A>B is considered to be true if (.A-B) is greater than or equal to -QCTx( U)f( |B) , and A>B is considered true if AZB is true and A=B is not. The comparison tolerance OCT is typically set to the value 1S~13. The setting OCT+Q is also useful since it yields absolute comparisons, but may lead to unexpected results due to the finite precision of the representation of numbers. For example, if the maximum precision is 16 20 APL Language decimal digits and all digits are displayed in printing, then: QCT+O X 0.6666666666666667 Y-f-3x* 1-2 2.2204460'+9250313£' 16 2 = 1 0CT+1E 13 2 = Y 1 When applied to boolean arguments only, the relations are, in effect, boolean functions, and denote functions which may be familiar from the study of logic, although referred to by different names and symbols. For example, X*Y is the exclusiye- or of X and Y, and XzY is material implication . This association should" be clear from the following table, which lists in the first two columns the four possible sets of values of two boolean arguments, and in the remaining columns the values of the 16 possible boolean functions, with the symbols of the boolean and relational functions of APL appended to appropriate columns : A B A f B 0000000011111111 01 0000111100001111 10 0011001100110011 11 01010101010 10101 A > < * V V = £ <. *< The ten functions listed at the foot of this table embrace all non-trivial boolean functions of two arguments. Consequently, any boolean expression of two arguments X and Y can be replaced by a simple APL expression as follows: evaluate the expression for the four possible cases, locate the corresponding column in the table, then use the function symbol at the foot of the column, or, if none occurs, use X or Y or ~X or ~Y or or 1 as appropriate. MINIMUM AND MAXIMUM The functions denoted by L and r perform as expected from their names. For example: X+~3 "2 "1 0. 1 2 3 Y+-3 2 1 "1 "2 "3 X[Y 3 2 10 12 3 XlY "3 2 "1 "1 "2 ~3 FLOOR AND CEILING The floor function L yields the integer part of its argument, that is, IX yields the largest integer which does not exceed X. Similarly, [X yields the smallest integer which is not less than X. For example: X-f-~3.lt 2.718 IX \X ~4 2 "3 3 "4 2 ~3 3 .Section 3: Primative Functions and Operators 21 The ceiling and floor functions are affected by the comparison tolerance OCT as follows: if there is an integer I for which \X-I does not exceed the value of OCT, then both IX and {X equal I. For example, if results are represented and printed to 16 decimal digits, then: J«-3x2*3 QCT+1E~13 ncT+o IX 2 IX [X 3 \X ROLL (Random number function) The roll is a monadic function named by analogy with the roll of a die; thus ?6 yields a (pseudo-) random choice from i"6, that is the first six integers beginning- with either or l according to the value of the index, origin UIO. For example: UI0+-1 ? 6 ? 6 ? 6 15 3 ?6 666666666666 4215563 4 5 114 5 UIO+O ? 6666666666666 0202435 5 30324 The domain of the roll function is limited to positive integers. The roll function employs an algorithm due to D.H. Lehmer; the result for each scalar argument X is a function of X and of the random link variable URL. The result of the roll function is system dependent but typically for X<2*31 is equal to UIO plus the integer part of X*URL*~1+2*31. POWER, EXPONENTIAL, GENERAL AND NATURAL LOGARITHM For non-negative integer right arguments the power function X*N is simply defined as the product over N repetitions of X. It is generalized to non-positive and non-integer arguments so as to preserve the relation that X*A+B shall equal (X*A )x(X*B ) . Familiar consequences of this extension are that x*-N is the reciprocal of X*N, and x**N is the Nth root of X. For example: 2*~3 "2 "1 1 2 3 .125 .25 .51248 64**1 2 3 4 5 6 64 8 4 2.828 2.297 2 The indeterminate case 0*0 is defined to have the value l. The domain of the power function X*Y is restricted in two ways: if Z=0, then Y must be non-negative; if X<0, then Y must be an integer or a (close approximation to a) rational number with an odd denominator. For example, ~8*.5 yields a domain error, but ~8*1*3 and ~8*2*3 yield ~2 and 4, respectively. The exponential function *X is equivalent to the expression e*X, where e is the base of the natural logarithms, approximately 2, .71828. 22 APL Language For example: *~2 "10 12 0.1353352832 . 367 879441 2 1 2.718281828 7.389056099 The natural logarithm function ®X is the inverse of the exponential, that is, *®X and ®*X both equal X. For example: • 1 2 3 4 0.6931471806 1.098612289 1.386294361 r *®l 2 3 4 12 3 4 «*1 2 3 4 12 3 4 The domain of the natural logarithm function is limited to positive numbers. The general logarithm function B*X is defined as (®X)*®B. It is inverse to the power function in the following sense: B*B*X and B®B*X both equal X. Limitations on the domain follow directly from the defining expression. CIRCULAR, HYPERBOLIC, AND PYTHAGOREAN FUNCTIONS The symbol o denotes a monadic function whose result equals pi times its argument. For example: oi 2 .5 3.141592654 6.283185307 1.570796327 The symbol o is also used dyadically to denote a family of fifteen related functions as follows: the expression iox is defined for integer values of I from "7 to 7, and is in each case equivalent to one of the circular, hyperbolic, or pythagorean functions as indicated in Figure 3.1. The arguments for the circular functions Sin, Cos, and Tan (iox, 2oX, and 3oz) are in radians. For example: PJ-HDl 10PI*2 3 4 1 0.8660254038 0.7071067812 The hyperbolic functions sinh and cosh are the odd and even components of the exponential function ; . that is, 5oX is odd, 60* is even, and the sum (5oZ)+(6oZ) is equivalent to *X. Consequently: 5oX equals . 5x(*X) -i*-X) &oX equals . 5x( *X)+(*-X) The definition of the hyperbolic tangent is analogous to that of the tangent, that is, 7ox equals (5oX)*6oX. The. three pythagorean functions oox, 4ox, and ~4oX are defined as in Figure 3.1, and are related to the properties of a right triangle as Section 3: Primative Functions and Operators 23 indicated in Figure 3.3. They may also be defined as follows: "40X equals oox equals 40X equals 50 20 6O 6 OX 'lox or '50X 10 20X 1 A >^ E D AC-\ AB=OOBC BC=OOAB AE=^ODE DE- koAE I B The Pythagorean Functions Figure 3.3 Each of the family of functions lox has an inverse in the family, that is, (-I)oX is the inverse of lox. Certain of the functions are not monotonic, and their inverses are therefore many-valued. The principal values are chosen in the following intervals: Arcosh i?«-~60X i?S0 R+ 4oX J? 2 Arccos R+ 2 ox (i?S0)A(i?<Ol) Arc sin R*- lox ( |fl)<o.5 R+- OOX i?20 f?«- 4 OX i?>0 FACTORIAL AND BINOMIAL FUNCTIONS For positive integer arguments, the factorial function \N is defined as the product of all positive integers up to N. An important consequence of this definition is that IN equals ffx'.jy-i, or, equivalently IN-l equals (IN)*N. This relation is used to extend the function to non-integer and negative arguments. For example: ff+1 2 3 4 5 IN 1 2 6 24- 120 ( IN)*N 1 1 2 6 24 !0 1 2 3 4 1 1 2 6 24 Ft- . 5 1 1.5 2 2.5 IF 0.8862269255 1 1.329340388 2 3.32335097 ( \F)iF 1.772453851 1 0.8862269255 1 1.329340388 !~.5 .5 1 1.5 1.772453851 1 0.8862269255 1 1.329340388 This extension leads to the expression (ro)*0, or 1*0 for ! "1 , and "1 is therefore excluded from the domain of factorial, as are all negative integers. 24 APL Language The binomial function M\N is defined, for non-negative integer arguments, as the number of distinct ways in which M things can be chosen from N things. The expression ( \N)i ( !M)x( IN-M) yields an equivalent definition which is used to extend the definition to all numbers. Although the domain of factorial excludes negative integers, the domain of the binomial does not, since any implied division by zero in the numerator \N is invariably accompanied by a corresponding division by zero in the denominator; the function therefore extends smoothly to all numbers. The result of UN is equivalent to coefficient I in the binomial expansion (X+1)*N . For example: 1 2 3 !3 13 3 1 OPERATORS An operator may be applied to a function to yield a different function. For example, the outer product operator denoted by the symbols ° . may be applied to any of the primitive scalar dyadic functions to produce a corresponding "table function" as illustrated below for times and power ; A+l 2 3 A° . xA 2 3 4 i+6 8 6 9 12 8 12 16 A» .*A 111 4 8 16 9 27 81 16 64 256 Four of the APL operators - reduction , scan , inner product , and outer product - apply to any primitive scalar dyadic function. The axis operator applies to reduction and scan , and also to certain of the mixed functions. REDUCTION Reduction is denoted by the symbol / and applies to the function which precedes it. For example, if V+-1 2 3 4 5, then +/V yields the sum of the items of V, and x/7 yields their product: t/V x/P 15 120 In general, an expression of the form f/V is equivalent to the expression obtained by placing the function symbol f between adjacent pairs of items of the vector V: r/v -/V ir2r3T4r5 1-2-3-4-5 The last example points up the fact that the general rule for the order of execution is applied, and that as a consequence the expression -/V yields the alternating sum of the items of V. The alternating sum is defined as the sum obtained after first weighting the items by Section 3: Primative Functions and Operators 25 multiplying alternate elements by l and l . Thus : A+l ~1 1 "1 1 VxA 12 3 4 5 + /VxA ■IV 3 3 Similarly, r/V yields the alternating product ; V*A 1 .53 .25 5 x/V*A 1.875 */V 1.875 The result of applying reduction to any scalar or vector is a scalar; the value in the case of a scalar or one-element vector argument is the single item itself. The application of reduction to other arrays is treated in the discussion of the axis operator. Reduction of an empty vector by any function is defined as the identity element of the function if one exists, i&§> a domain error if not. Thus if V is an empty vector, +/V equals 0, and a/7 equals 1. The reason for this definition is the extension to empty vectors of an important relation between the reductions of two vectors P and Q and the reduction of the vector V+P.Q obtained by chaining them together. For example: +/7 equals (+/P) + (+/<2) x-/V equals (x/p)x(x/Q) If P is an empty vector it is clear that +/P must equal (the identity element of +) , and that x/p must equal 1. SCAN The scan operator is denoted by the symbol \ and applies to the function which precedes it. When the resulting function is applied to a vector V it yields a vector of the same shape whose Kth element is equal to the corresponding reduction over the first K elements of V. For example : +\1 2 3 4 5 1 3 6 10 15 x\l 2 3 4 5 1 2 6 24 120 V\0 10 1 111 A\l 10 10 110 <\0 10 110 10 The extension of scan to arrays other than vectors is treated in the discussion of the axis operator. 26 APL Language AXIS Since reduction is defined on vectors, and since a matrix can be conceived as a collection of row vectors, the result of reduction on a matrix could be defined as the vector of results obtained by reduction of each of the row vectors. However, a matrix can also be viewed as a collection of column vectors, and reduction could be defined accordingly. It is therefore important to be able to specify which set of vectors is to be reduced. The row vectors extend along the second axis of the matrix, and are each of length equal to the length of that axis. Similarly, the column vectors extend along the first axis and, in general, the index of an axis identifies a set of vectors in an array of any non-zero rank. The axis operator is denoted by brackets enclosing an expression which yields the index of an axis as a one-element vector or a scalar. It determines the direction of application of any scan or reduction operator whose symbols immediately precede it. For example: M-e-3 4pil2 +\[1]M +\[2]M 1234 1234 136 10 5/678 6 8 10 12 5 11 18 26 9 10 11 12 15 18 21 24 9 19 30 42 +/111M 15 18 21 24 +/L21M 10 26 42 The shape of the result of scan equals the shape of the argument. The shape of the result of reduction equals the shape of the argument except that the indicated axis of reduction is removed. The indexing of axes depends on the index origin 010. If no axis operator occurs, reduction and scan apply along the last axis. The symbols / and \ also denote reduction and scan, but in the absence of axis operators they apply along the first axis . The axis operator is also used to specify the axis of application of the mixed functions reverse , rotate , compress , and expand . INNER PRODUCT If P and Q are vectors of the same' shape, then the expression +/PxQ has a variety of useful interpretations. For example, if P is a list of prices and Q a list of corresponding order quantities, then +/PxQ is the total cost. Expressions of the same form employing functions other than + and x are equally useful, as suggested by the following examples (where B is used to denote a boolean vector} : a/P=Q Comparison of P and Q. +/P=Q Count of agreements between P and Q. l/P+Q Minimum distance for shipment, where P represents the distances from source to transhipment points and Q the distances from these points to the destination. +/PxB Sum over a subset of P specified by B. */P*B Product over a subset of P specified by B. The inner product produces functions equivalent to expressions in this form; it is denoted by. a dot and applies to the two functions which surround it. Thus P+.xQ is equivalent to +/Px#, and Px.*B is equivalent Section 3: Primative Functions and Operators 27 to x/p*p, and, in general, Pf.gC is equivalent to f/PgQ, if P and Q are vectors. The inner product is extended to arrays other than vectors along certain fixed axes, namely the last axis of the first argument and the first axis of the last argument. The lengths of these axes must agree. The sh ape of the result is obtained by deleting these axes and chaining the remaining shape vectors together. The consequence for matrix arguments is illustrated in Figure 3.4. The consequences for the shape of inner products on some other arrays are illustrated below: Q.G Q.H 7 7 ( scalar ) pGf.gH Q.A B.S. 3 5 ^5 2 7 7 9 9 1 ^ 3 2 7 pAf.gB 7 pCf .go pEf.gF Formally, pAf.gB equals ( 1+pA) ,1+pB. The inner product M+.*N is commonly called the matrix product. Examples of it and other inner products follow: P«-2 3 5 7 M W+ . xM 1111 1234 0111 0123 0011 0012 0001 0001 M+.*P 17 15 12 7 P+ . x-M 2 5 10 17 MA.=Af 1 Px . *M 2 6 30 210 M- . xM 1 _0 1 _0 10 1 1 _o 1 MA. 10 = 0011 Figure 3.4: Inner Product 28 APL Language Either argument of an inner product may be a scalar; it is extended in the usual manner. For example, A+.*l is equivalent to + /A, and l+.xA is equivalent to +/A. OUTER PRODUCT The outer product operator, denoted by the symbols °. preceding the function symbol, applies to any dyadic primitive scalar function, so that the function is evaluated for each member of the left argument paired with each member of the right argument. For example, if ii-f-1 2 3 and S-e-l 2 3 4 5: A" . xB 12 3 4 5 2 4 6 8 10 3 6 9 12 15 Ao ,<B 1111 111 11 Such tables may be better understood if labelled in a way widely used in elementary arithmetic texts: values of the arguments are placed beside and above the table, and the function whose outer product is being computed is shown at the corner. Thus: B B * 1 1 1 2 2 3 3 4 4 5 5 < 1 1 2 3 4 5 1 1 1 1 1 1 1 1 2 1 2 4 6 8 10 A 2 1 1 1 1 3 1 3 6 9 12 15 3 1 1 1 In the foregoing example the shape of the result A°.*B is clearly equal to (piO.(pS). This expression yields the shape for any arguments A and B. Thus if R+-A°.+B and A is a matrix of shape 3 4 and B is a three-dimensional array of shape 5 6 7, then R is a five-dimensional array of shape 3 4 5 6 7. Moreover, RH ;J ;K;L;M1 equals ALI;J1+BLK;L ;Ml for all possible values of the indices. MIXED FUNCTIONS The mixed functions are grouped in five classes according to whether they concern the structure of arrays , selection from arrays , the generation of selector information for use by selection functions, numerical calculations, or transformations of data such as that between characters and numbers. All are listed in Figure 3.5 together with brief definitions or examples. Those functions which may be modified by an axis operator may also be used without an axis operator, in which case the axis concerned is the last, or, in the case of the functions denoted by e and by /, the first. Section 3: Primative Functions and Operators 29 Name Sign Definition or example Shape Reshape Ravel Reverse Rotate s Catenate Transpose 3 pA VqA ,A $A Ai>A A, A VQA QA p p is n p e is 3 4 p5 is i0 Reshape a to dimension v 3 4pil2 is E 12pE is 112 OpE is i0 ,A is (y./pA)pA ,E is il2 p,5 is 1 DCS A IJKL W is HGFE *[1]X is ex is EFGH LKJI $P is 7 5 3 2 /1BCD 3<t>P is 7 2 3 5 is ~l<t>f> 1 ~1(|>X is SFGH P,i2 is 235712 <T','HIS' is 'THIS' AEI Coordinate I of 4 2 IS)* is BFJ becomes coordinate CGK VLI] of result i i$£ is l 6 ll DHL Reverse order of coordinates §E is 2 lS)ff Take Drop Compress Expand Indexing V+A V\A VIA V\A VIA1 MIA; A] ALA;. . ..;4] } Take or drop |f[I] first 2 3+X is 4SC > (Vlllzo) or last (F[I]<0) EFG ) elements of coordinate j ~2+P is 5 7 1 3 10 1 0/P is 2 5 10 1 0/E is 5 7 9 11 1 1/[1]£ is 1 2 3 1+ is 1 HE 9 10 11 12 A BCD 1 l\i2 is 102 1011 1\X is E FGH I JKL P[2] is 3 P'[ 4 3 2 1] is 7 5 3 2 E[l 3;3 2 1] is 3 2 1 11 10 9 E[l;] is 1 2 3 4 .4BCD E[;l] is 1 5 9 ' ABCDEFGHIJKL' [E] is EPfffl Index: generator Index of Membership Grade up * Grade down Deal" \S V\A AeA kv yv s?s First s integers it is l 2 3 4 i0 is an empty vector Least index of A Pi 3 is 2 5 12 5 in v, or l+pf PxE is 3 5 4 5 4 4l4 is 1 5 5 5 5 110 pWeY is B W EsP is l o 1 Peil is 1 1 0000 ■) The permutation which A3532is4l32 Would order v (ascend- ) ing or descending) f3 532 is 2134 W?X is Random deal of w elements from iY Matrix inverse Matrix division Decode Encode SM MMM AxA ATA B2 2pl 1 1 is l ~i arguments may 1 be scalars, (2 2pP)@2 2pl l o l is ~3 "4 vectors, or 5 7 matrices 1011 7 7 6 is 1776 24 60 60ll 2 3 is 3723 24 60 60T3723 is 1 2 3 60 60T3723 LB 2 3 Execute Format , monadic Format , dyadic i.V VIA l'lt2' is 3 i'P' is 2 3 5 7 '~1 .5'a.=t~1 . 5 is 1 pTE is 3 12 X is jX UP is 4 1TP is 2.0 3.0 5.0 7.0 ~1TP is 6 "lfP is 2E00 3E00 5E00 7EO0 Notes to Figure 3.5 1 . Restrictions on argument ranks are indicated by: S for scalar, V for vector, M for matrix, and A for any array. Except as the left argument of Si A or SZA1 , or the argument of -i and t, a scalar may be used in place of a vector. A one-element vector may replace any scalar. 2. Arrays used in examples: P 2 3 5 7 E 12 3 4 5 6 7 8 9 10 11 12 X ABCD EFGH IJKL 3. Function depends on index origin. t. Elision of any index selects all along that axis. 5. The function is applied along the last axis; the symbols 1, \, and e are equivalent to /, \, and if, respectively, except that the function is applied along the first axis. In general, the relevant axis is determined by [VI after the function symbol. Figure 3.5: Primitive Mixed Functions 30 APL Language A scalar may be used in place of a one-element vector: a. as left argument of reshape 3 pit -*--* (,3)p^ take 3 -M 5 ■*--»■ ( , 3 ) 1 1 5 drop 34-i5 «-»■ ( , 3 ) + 1 5 expand 1 \ . 5 ■<--»■ ( , 1 ) \ , 5 transpose IS?, 5 ■*■■*■ (,1)<?,5 format 5f3.2 +•+ (,5)T3.2 «-+ 5 T3.2 b. as right argument of execute *'P' ■*■+ 4,'P 1 branch -»-4 ■<-•*• '-*-,4 A scalar is extended to conform to a vector: a. as left argument of compress 1/ i3 ++ 1 1 1 / i3 rotate l<t>2 2 pit +■-* 1 1 <J> 2 2pi<+ b. as right argument of compress 101/2 •*-->■ 101/222 expand 1 1 \ 2 «--*• 1 1 \ 2 2 A one-element vector is permitted in place of a scalar: a. as left argument of deal (,3)?5 ++ 3?5 b. as right argument of index generator i , 5 ■*--+ i 5 deal 3?, 5 •*--* 3?5 Figure 3.6: Scalar-Vector Substitutions for Mixed Functions Figure 3.5 gives restrictions, in summary form, on the ranks of arguments which may be used with each mixed function. Figure 3.6 shows for what mixed functions and under what conditions scalar and vector arguments may be substituted for each other. STRUCTURAL FUNCTIONS In the monadic structure functions the argument may be of any type, numeric or character. In the dyadic selection and structure functions one argument may be of any type and the other (which serves as an index or other selection indicator) must be numeric, and xn two cases (compression and expansion) is further restricted to be boolean. Shape Reshape and Ravel The monadic function p applied to an array A yields the shape of A, that is, a vector whose components are the dimensions of A. For Section 3: Primative Functions and Operators 31 example, if A is the matrix 2 3 6 7 10 11 12 of three rows and four columns, then pA is the vector 3 4. Since pA contains one component for each axis of A, the expression ppA is the rank of A. Figure 3.7 illustrates the values of pA and ppA for arrays of rank o (scalars) up to rank 3. In particular, the function p applied to a scalar yields an empty vector . Type of Array pA ppA pppA Scalar Vector Matrix 3-Dimensional N M N L M N 1 2 3 1 1 1 1 Figure 3.7 SHAPE AND RANK VECTORS The monadic function ravel is denoted by a comma; when applied to any array A it produces a vector whose elements are the elements of A in row order. For example, if A is the matrix: 2 10 18 4 12 20 6 14 22 16 24 and if V+,A , then V is a vector of dimension 12 whose elements are the integers 2 4 6 8 10 12 ... 24- If A is a vector, then ,A is equivalent to A; if A is a scalar, then ,A is a vector of length l. The dyadic function p reshapes its right argument to the shape specified by its left argument. If M+DpV, then M is an array of dimension D whose elements are the elements of V. For example, 2 3p 123456 is the matrix If n, the total number of elements required in the array DpV, is equal to the dimension of the vector V, then the ravel of DpV is equal to V. If N is less than pv , then only the first N elements of V are used; if N is greater than pV , then the elements of V are repeated cyclically. For example: 2 3pl 2 2 1 1 2 3 3pl 10 10 1 More generally, if A is any array, then DpA is equivalent to Dp ,A- For example: A 12 3 4 5 6 3 5pA 2 3 4 12 3 6 12 The expressions OpX and o 3pX and o OpJ are all valid; any one or more of the axes of an array may have zero length. Such an array is called an empty array . If D is an empty vector, then DpA is a scalar. 32 APL Language Reverse and Rotate The monadic function reverse is denoted by <|> ; if x is a vector and K+QX , then k is equal to x except that the items appear in reverse order. The axis operator applies to reversal and determines the axis along which the vectors are to be reversed. For example: A $[114 <t>[2lU 123 H56 321 456 123 6 5 4 The expression $A denotes reversal along the last coordinate of A , and ba denotes reversal along the first coordinate. For example, if A is of rank 3, then $A is equivalent to <$[3]A , and qA is equivalent to 4>[l]i4. The dyadic function rotate is also denoted by (J> . If if is a scalar or one-element vector and x is a vector, then Ki?X is a cyclic rotation of x defined as follows: K$X is equal to z[i+ ( p j) | ~l+K+\pXl . For example, if x<-2 3 5 7 11, then 2$X is equal to 5 7 11 2 3 , and ~2$X is equal to 7 11 2 3 5. In o-origin indexing, the definition for K$X becomes XL (p X) \ K+ ipZ] . If the rank of x exceeds 1 , then the coordinate J along which roatation is to be performed may be specified by the axis operator in the form z-*-K$LJlX. Moreover, the shape of K must equal the remaining dimensions of x, and each vector along the Jth axis of x is rotated as specified by the corresponding element of K. A scalar K is extended in the usual manner. For example, if p x is 3 4 and J is 2 , then the shape of K must be 3 and Z[J;3 is equal to £[J]4>J[I; ] . If J is 1 , then pK must be 4, and Z[;J] is equal to X[I]<t>X[ ;T] . For example: M 1 2 3<)>[1]M 1 2 3C|)[2]W 1 2 3 4 1 6 11 4 2 3 4 1 5 6 7 8 5 10 3 8 7 8 5 6 9 10 11 12 9 2 7 12 12 9 10 11 The expression K&X denotes rotation along the first axis of x. Catenate and Laminate Catenate , denoted by a comma, chains vectors (or scalars) together to form a vector. For example: X+2 3 5 7 11 X,X 2357 11 2357 11 In general, the dimension of x ,Y is equal to the total number of elements in x and y. A numeric vector cannot be catenated with a character vector. The axis operator applies to catenate and determines the axis along which vectors are to be catenated. For example; M-i-3 3p 'ABCDEFGHI< M M, [1]M M. ,[2]M M,M ABC ABC ABCABC ABCABC DEF DEF DEFDEF DEFDEF GHI GHI ABC DEF GHI Section 3: GHIGHI Primative Funct GHIGHI ions and Op 33 Two arrays are conformable for catenate along axis I if all other elements of their shapes agree. Moreover, two arrays may be catenated along axis I if they differ in rank by 1 and if the shape of the array of lower rank equals the shape of the array of higher rank after dropping item I from it. For example: V^'PQR' M.IX1V M,L21V M.V ABC ABCP ABCP DEF DEFQ DEFQ GHI GHIR GHIR PQR A scalar argument of catenate will be replicated to form a vector as required. For example: <7,(C,[1] W.C1] C) ,C mm® EWBCS [SOfi'FS BCfflffl mmm Laminate joins two arrays of identical rank and shape along a new axis. The position of the new axis relative to the existing axes is indicated by a fractional axis number. For example, if the new axis is to be inserted between the existing axes 1 and 2 , the axis number must have a value between 1 and 2 . If the new axis is to be inserted ahead of the present first axis, the axis number must be between and 1 (or, if zero-origin indexing is used, between ~1 and 0). Similarly, if the new axis is to be after the last of the present axes, the axis number must exceed the index of the present last axis by a fraction between and 1 . The result of lamination has rank 1 greater than the rank of the arguments, and has the same shape except for the interpolation of the new axis, along which it has length 2. The comma, which normally denotes catenation, followed by an axis operator associated with a non-integral index produces lamination. For example: 5] 217 W-<-3 3p 'ABCDEFGHI' 2N-3 3p '123456789' M M,l ABC ABC DEF DEF GUI N GHI 123 123 456 456 789 789 M. ,[1. .5] 217 M,L2.51N ABC Al 123 B2 C3 DEF 456 04 2?5 GHI F6 789 Gl H8 J9 The shapes of the foregoing laminations are 2 3 3 and 3 2 3 and 3 3 2; the position of the 2 shows the point of new axis insertion in each case. 34 APL Language A scalar argument of laminate is extended as required example : For B-<-2 2p'1234' B,[2.5]'+' 1 + 2 + 3 + 4 + ,B,[2.5]»+» 1+2+3+4+ Transpose The expression 2 1W yields the transpose of the matrix M; that is, if i?x-2 1§M , then each element R[I;Jl is equal to MM ill. For example : ' M 2 ltytf 1 2 3 4 1 5 9 5 6 7 8 2 6 10 9 10 11 12 3 7 11 4 8 12 If p xs any permutation of the indices of the axes of an array A then ptstA is an array similar to A except that the axes are permuted: the jth axis becomes the p[T]th axis of the result. Hence, if E<-p<siA , then (pi?)[P] is equal to pA . For example: A+2 3 5 7pi210 PA 2 3 5 7 P-e-2 3 4 1 pPM 7 2 3 5 More generally, q§a is a valid expression if Q is any vector equal in length to the rank of A which is "complete" in the sense that if its items include any integer N they also include all positive integers less than n. For example, ±f ppA is 3, then 112 and 2 11 and 111 are suitable values for q but 1 3 1 is not. Just as for the case P§A where P is a permutation, the Jth axis becomes the Q[l]th axis of Q§A. However, in this case two or more of the axes of .4 may map into a single axis of the result, thus producing a diagonal section of A as illustrated below: 4-e-3 3pl9 S-t-3 5pil5 A B 12 3 12 3 4 4 5 6 6 7 8 9 7 8 9 11 12 13 14 1 1§A 1 l(sjB 15 9 1 7 13 5 10 15 The monadic transpose ts>A reverses the order of the axes of its argument. Formally, ts>A is equivalent to (<t>ippd)*}d. In particular, for a matrix a this reduces to 2 1 ^ and is what is commonly called the transpose of a matrix. Section 3: Primative Functions and Operators 35 SELECTION FUNCTIONS The selection functions are all dyadic; one of the arguments may be. an array of any type, and the other, which will be referred to as the selector because it serves to specify the selection to be made, must be numeric, and, in the case of expand and compress , is further restricted to boolean. Take a nd Drop If s is a non-negative scalar integer and V is a vector, then S + V is a vector of dimension s obtained by taking the first S elements of V followed (if s>pV) by zeros if v is numeric and by spaces if it is not. For example: 3+2 3 5 7 7 + 2 3 5 7 235 2357000 3+MBCDE 1 a+'ABCDE' ) ,*@' ABC ABODE @ If 5 is a negative integer, then s + V takes elements as above but takes the last elements of v and fills as needed on the left. For example : 3+2 3 5 7 3 5 7 7+2 3 5 7 2 3 5 7 If a is any array, then w+A is valid only if the vector W has one element for each axis of a, and will determines what is to be taken along the jth axis, of 4. For example: A+3 4pil2 A 12 3 4 5 6 7 8 9 10 11 12 12 3 5 6 7 2 3+4 "3+4 2 3 4 6 7 8 6 10 '2 6+4 7 11 12 The function drop U) is defined analogously, except that the indicated number of elements are dropped rather than taken. For example, "1 n-A is the same, matrix as the result of 2 ~3+4 displayed in the preceding paragraph. If the number of elements to be dropped along any axis equals or exceeds the length of that axis, the resulting shape has a zero length for the axis. The rank of the result of the take and drop functions is the same as the rank of the right argument. Compress and Expand The expression u/X denotes compression of X by U. If U is a boolean vector and x is a vector of the same dimension, then U/X produces a vector of +/y elements chosen from those elements of X corresponding to non-zero elements of u. For example, if X+2 3 5 7 11 and u+1 110 then u/X is 2 5 7 and (~U)/X is 3 11. C+'THIS IS AN EXAMPLE' D+-C*' ' Cl+D/C CI THISISANEXAMPLE To be conformable, the dimensions of the arguments must agree, except that a scalar argument is extended. Hence l/X is equal to X and q/X is an empty vector. 36 APL Language Expansion is the converse of compression and is denoted by u\X . If I<-U\X, then u/Y is equal to x and (~y)/j is an array of zeros or spaces according as x is numeric or character. In other words, u\X expands x to the format indicated by the ones in u and fills in zeros or spaces. To be conformable, +/u must equal p x. D\C1 THIS IS AN EXAMPLE The axis operator applies to both compress and expand and determines the axis along which they apply. If the axis operator is omitted, the last axis is used. The symbols / and \ also denote compression, but when used without an axis operator apply along the first axis. Q+3 hp'ABCDEFGHIJKL' ABCD EFGH IJKL ABCD EFGH IJKL ABCD EFGH IJKL 110 1\[1]< 1 1 1\( BC FG JK ABCD IJKL ABCD IJKL Oil 0/<3 1 1/lllQ 1 1/Q The rank of the result of compress or expand equals the rank of the right argument. Indexing Indexing may be either p- origin or l- origin as discussed in Section 2. The following discussion assumes l-origin. If x is a vector and I is a scalar, then XLH denotes the jth element of x. For example, if X+2 3 5 7 11 then x[2] is 3. If the index j is a vector, then xlH is the vector obtained by selecting from x the elements indicated by successive components of j. For example, xil 3 5] is 2 5 11 and XL 5 4 3 2 l] is n 7 5 3 2. If the elements of j do not belong to the set of indices of x, then the expression x[r] evokes an index error report. In general pXZH equals p j. In particular, if j is a scalar, then XLH is a scalar, and if j is a matrix then x[j] is a matrix. For example: A+-<ABCDEFG' I«-4 3p3 1 t 2 1 1 1 1 2 1 1 1 I 3 1 4 CAD 2 1 4 BAD 4 1 2 DAB 4 1 4 DAD ALII If M is a matrix, then m is indexed by a two-part list of the form 1% J where 1 selects the row (or rows) and j selects the column (or Section 3: Primative Functions and Operators 37 columns) . For example: M M[2;3] Mil 3;2 3 4] 1234 7 234 5 6 7 8 10 11 12 9 10 11 12 In general, pMH;J~\ is equal to (pI),pJ. Hence if J and J are both vectors, then Mil; J~\ is a matrix; if both I and J are scalars, MiI;J'] is a scalar; if I is a vector and J is a scalar (or vice versa) , MiI;J'} is a vector. The indices are not limited to vectors, but may be of higher rank. For example, if I is a 3 by 4 matrix, and J is a vector of dimension 6, then Mil; J] is of dimension 3 4 6, and MiJ;I~\ is of dimension 6 3 4. In particular, if T and P and Q are matrices, and if R+TIP TlPlI ], then R is an array of rank 4 and PC J ;J;K;L] is equal to iJliQlK-.Ll . The form Mil;'] indicates that all columns are selected, and the form Mi;J~\ indicates that all rows are selected. For example, Mi 2 ; ] is 5 6 7 8 and Mi ; 2 1] is the matrix with rows 2 1 and 6 5 and 10 9. The following example illustrates the use of a matrix indexing a matrix to obtain a three-dimensional array: A/f-2 4p 31421441 M Mi ;M] 3142 4321 1441 3223 4 114 1111 An indexed variable may appear to the left of a specification arrow if (1) the expression is executable in the environment and (2) denoting the values of the expression on the left and right by L and R, then l=x/pR or (l*p£)/p£ must equal ( l*pP)/pP. For example: X+2 3 5 7 11 XI 1 3]-*-6 8 X 6 3 8 7 11 SELECTOR GENERATORS All of the functions in this group have integer results which, although they are commonly useful as the selector argument in selection functions, are often used in other ways as well. For example, the grade function i is commonly used to produce indices needed to reorder a vector into ascending order (as in XiiX]) , but may also be used in the treatment of permutations as the inverse function, that is, ^P yields the permutation inverse to P. Similarly, \N generates a vector of N successive indices, but . lxiff generates a grid of values with an interval of . 1 . Index Generator and Index of The index generator i applies to a non-negative scalar integer N to produce a vector of length N containing the first N integers in order, beginning with the value of the index origin DIO . For example, r5 yields 12 3 4 5 (in 1-origin) or 1 2 3 4 (in 0-origin) , and iO yields an empty vector. A one-element vector argument is treated as a scalar. If V is a vector and S is a scalar, then V\S yields the index (in 38 APL Language the origin in force) of the earliest occurence of s in v, that is, the index of S in V. If S differs from all items of v, then V\S yields the first index outside the range of V, that is, UlO+pV. If S is any array, then V\S yields an array of the shape of s, each item being determined as the index in v of the corresponding item of S. For example: A+'ABCDEFGHIJKLMNOPQRSTUVWXYZ ' J+A I ' HEAD CHIEF ' M«-2 5p' J M 8 5 1 4 27 3 8 9 I 5 6 HEAD AU1 CHIEF HEAD CHIEF A\M AlbJl 8 5 1 4 27 FEIHC DAEH 3 8 9 5 6 A\ 'VAB3 1 22 1 18 28 Membership HEAD CHIEF' The function XeY yields a boolean array of the same shape as x. Any particular element of XeY has the value l if the corresponding element of x belongs to Y, that is, if it occurs as some element of y. For example, (i7)e3 5 is equal to 0010100 and » ABCDEFGH' e' COFFEE' equals 00101100. The right argument y may be of any rank. The selector argument of compression is commonly provided by application of the membership function, alone or in combination with the scalar boolean and relational functions. Grade Functions The grade up function &v grades the items of vector v in ascending order, that is, it yields a result of the same dimension as v whose first item is the index (in the origin in force) of the smallest item of V, whose second item is the index of the next smallest item, and so on. Consequently, the expression VlbVl yields the elements of V in ascending order. For example, if 7*8 3 7 5, then |Hs 2 t 3 1 and VLiVl is 3 5 7 8. If the items of V are not all distinct, the ranking among any set of equal elements is determined by their position. For example, A4 3 1 3 4 2 yields 3 6 2 4 15. The grade down function yv grades .the items of V in descending order; among equal elements the ranking is determined by position just as for grade up. Consequently, yv equals the reversal of |7 only if the items of V are distinct. For example: A+7 2 5 11 3 iA 2 5 3 14 4 13 5 2 B«-4 3 13 4 2 iB 3 6 2 4 15 15 2 4 6 3 The grade functions apply only to vectors, Deal The function M?N produces a vector of length M obtained by making M (pseudo-) random selections, without replacement, from the population Section 3 : Primative Functions and Operators 39 \N. Both arguments are limited to scalars or one-element vectors. Each selection is made by appropriate application of the scheme described for the function roll . The expression N?N yields a random permutation of the items of \N . The expression p[A/? p p] selects M distinct elements from the population defined by the items of a vector p . For example : GBD P*-<ABCDEFGH* PL3?pP] P[(pP)?pP] CEADHFGB NUMERICAL FUNCTIONS The numerical mixed functions apply only to numerical arguments and produce numerical results. Matrix Inverse and Matrix Divide The domino (g) represents two functions which are useful in a variety of problems including the solution of systems of linear equations, determining the projection of a vector on the subspace spanned by the columns of a matrix, and determining the coefficients of a polynomial which best fits a set of points in the least-squares sense. When applied to a non-singular matrix A the expression SU (matrix inverse) yields the inverse of A, and the expression X*-BM (matrix divide) yields a value of X which satisfies the relation a/ ,b=A+ .xX and is therefore the solution of the system of linear equations conventionally represented as Ax=b: A+i U)« . > u A m A+, . x@/l 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 B<-1 3 6 10 x+Bm B X 3 6 10 12 3 4 A+.xX 1 3 6 10 (1/1) + . *B 12 3 4 Ct-H 2pl 2 3 5 6 9 10 14 ■cm 10 14 A+. 1 2 3 5 6 9 10 14 xY (BA)+.xC The final example above shows that if the left argument is a matrix C, then c®A yields a solution of the system of equations for each column of C If A is non-singular and if j is an identity matrix of the same dimension, then the matrix inverse SU is equivalent to the matrix divide TIE4. More generally, for any matrix p, the expression @P is equivalent to the expression ( ( iP) o . = iP)ip, where R is the number of rows in P. The domino functions apply more generally to singular and non-square matrices, and to vectors and scalars; any argument of rank greater than 2 is rejected (RANK ERROR) . For matrix arguments A and B HO APL Language the expression x+B%A is executed only if 1. A and B have the same number of rows, and 2. the columns of A are linearly independent. If the _ expression X+BM is executable, then pX is equal to (i + Pi i) i + p b and X xs determined so as to minimize the value of the expression' + / AB-A+.xX)*2. The domino functions apply to vector and scalar arguments as follows: except that the shape of the result is determined as specified above, a vector is treated as a one-column matrix and a scalar is treated as a one-by-one matrix. The rationale for this interpretation of a vector as a one-column (rather than one-row) matrix is that the right argument is treated geometrically (as will be seen in a subsequent example) as defining a space spanned by its column vectors, and the left argument was seen (in an earlier example) to be treated so as to yield a solution for each of its column vectors. Indeed, a one-rowed matrix right argument (unless 1-by-l) would be rejected under condition 2 above . In the case of scalar arguments X and Y, the expression @J is equivalent to *y and, except that it yields a domain error for the case 0@0, the expression X®Y is equivalent to X*Y . The use of H for a singular right argument can be illustrated as follows: if x is a vector and Y+F X, then the expression Ym°.*Q,iD yields the coefficients of the polynomial of degree D which best fits (in the least squares sense) the function F at the points X. The definition of BMA has certain useful geometric interpretations. If B is a vector and A is a matrix, then saying that + /(.B-A + .*Bm)*2 is a minimum is equivalent to saying that the length of the vector B-A+.xBm is a minimum. But A+.xBftA is a point in the space spanned by the column vectors of A and is therefore the point in this space which is closest to B. In other words, P+A + . xBBA is the projection of B on the space spanned by the columns of A. Moreover, the vector B-P must be normal to every vector in the space; in particular, (B-P)+ .xA is a zero vector. If A and B are single-column matrices, then BEA is a l by 1 matrix and A+.xBM is equivalent to AxS , where S is the scalar "pBS^. if A and B are vectors, then BM is a scalar and the projection of B on A is therefore given by the simpler expression AxBm. For example: 4«-4.5 1.7 Bf-2 5 P+AxB%A P 3.403197926 1.28565255 N+B-P N 1.4-03197926 3.71434745 N+.xA 2.442490654£' - 15 Similar analysis shows that if A is a vector then m is a vector in the direction of A; that is, m is equal to SxA for some scalar S. Moreover, A+ .x$a is equal to l . In other words, m is the "image" of Section 3: Primative Functions and Operators 41 the vector A obtained by inversion in the unit circle (or sphere) Decode and Encode For vectors R and X , the decode (or base-value ) function R±X yields the value of the vector X evaluated in a number system with radices i?[l], RL 2] RtpRl. For example, if B+21 60 60 and x+l 2 3 is a vector of elapsed time in hours, minutes, and seconds, then RiX has the value 3723, and is the corresponding elapsed time in seconds. Similarly, 10 10 10 10 l 1 7 7 6 is equal to 1776, and 222x101 is equal to 5. Formally, RiX is equal to + /J/xX, where W is the weighting vector determined as follows: WLpWl is equal to 1 and WLJ-ll is equal to RLIlxWLIl. For example, if R is 24 60 60, then W is 3600 60 1. Scalar (or one-element vector) arguments are treated as usual. For example, 10 i 1 7 7 6 yields 1776. The arguments are not restricted to integers; for example, if X is a scalar then XiC is the value of the polynomial with coefficients C, arranged in descending order on the powers of X . The decode function is extended to arrays in the manner of the inner product operator: each of the radix vectors along the last axis of the first argument is applied to each of the vectors along the first axis of the second argument. There is one difference; if either of these distinguished axes is of length 1 , it will be extended (by replication of the element) as necessary to match the length of the other argument. Except for this different treatment of unit axes, the shape of the result of Ax.B is determined like the shape of the inner product, namely (~l + p4) ,1 + pB . The encode (or representation ) function RiX is, for certain arguments, inverse to the decode function. For example: i?«-10 10 10 10 i?±l 7 7 6 1776 i?Tl776 17 7 6 More generally, Rl{RjX) equals {*/R)\X rather than X. For example: 10 10 10 10T123 10 10 10T123 12 3 12 3 10 10T123 10T123 2 3 More precisely, the definition of the encode function is based on the definition of the residue function; for a vector left argument and scalar right argument, decode is equivalent to the E whose canonical representation is shown at the left below: Z+A E B 2 2 2T13 Z«-0xA 10 1 I+pA "2 "2 "2T13 L:-KI=0)/0 1 "1 1 ZZI1+ALI1\B 2 2T13 ■+U[I] = 0)/0 6 1 B+(B-ZLI1)*AII1 2 2 2T 13 I-t-I-1 11 +£, "2 2 2T13 11 42 APL Language The basic definition of RtX concerns a vector R and a scalar X , and produces a result of the shape of if . It is extended to arrays as follows: each radix vector along the first axis of R is applied to obtain the representation of each item of X , the resulting representations being arrayed along the first axis of the result. For example : 10 10 10T215 4-86 72 219 3 i?+-10 10 10,[1.5]8 8 8 2 4 2 R 18 7 10 10 8 5 6 2 9 3 1Q 8 10 8 i?Tl23 1 1 2 7 3 3 The expression for the shape of the result of RjX is the same as for the shape of the outer product, namely ( P R), p x. DATA TRANSFORMATIONS Of the two functions in this class, the format is a true type transformation, being designed to produce a character array which represents the data in its numeric argument. Over a certain class of arguments the execute function is inverse to the format and is therefore considered as a type transformation as well, although its applicability is, in fact, much broader. Execute and Format Any character vector or scalar can be regarded as a representation of an APL statement (which may or may not be well-formed) . The monadic function denoted by a. takes as its argument a character vector or scalar and evaluates or executes the APL statement it represents. When applied to a character array that might be construed as a system command or the opening of function definition, an error will necessarily result when evaluation is attempted, because neither of these is a well- formed APL statement. The execute function may appear anywhere in a statement, but it will successfully evaluate only valid (complete) expressions, and its result must be at least syntactically acceptable to its context. Thus, execute applied to a vector that is empty, contains only spaces, or starts with "-*• (branch symbol) or n (comment symbol) produces no explicit result and therefore can be used only on the extreme left. For example: 4' • VALUE ERROR Z«-±' ' A The domain of ± is any character array of rank less than two, and RANK and DOMAIN errors are reported in the usual way: C«-'3 4' +/aC ±3 4 7 DOMAIN ERROR 11 3pC 43 4- RANK ERROR a 1 1 3 pC A Section 3: Primative Functions and Operators 43 An error can also occur in the attempted execution of the APL expression represented by the argument of i ; such an indirect error is reported by the error type prefaced by the symbol 4 and followed by the character string and the caret marking the point of difficulty. For example : a. DOMAIN ERROR 4*0 A 1 * ) WSID ' 4 VALUE ERROR )WSID A The symbol <r denotes two format functions which convert numerical arrays to character arrays. There are several significant uses of these functions in addition to the obvious one for composing tabular output. For example, the use of format is complementary to the use of execute in treating bulk input and output, and in the management of combined alphabetic and numeric data. The monadic format function produces a character array which will display identically to the display normally produced by its argument, but makes this character array explicitly available. For example: M«-2=?4 4p2 R+lM M R 7?[;2xi4] 0101 0101 0101 0011 0011 0011 1011 1011 1011 0011 0011 0011 pM pi? 4 4 4 8 p<T2 5 Xf-34 3 X THE VALUE OF X IS ' ,lX TEE VALUE OF X IS 34 1 ABCD A/,i? = Ti? ▼ MBC7? 1 The format function applied to a character array yields the array unchanged, as illustrated by the last two examples above. For a numerical array, the shape of the result is the same as the shape of the argument except for the required expansion along the last coordinate, each number going, in general, to several characters. The format of a scalar number is always a vector. The printing normally produced by APL systems may vary slightly from system to system, but the result produced by the monadic format will have no final column of all spaces, and no initial spaces in the case of a vector or scalar argument. The dyadic format function accepts only numerical arrays as its right argument, and uses variations in the left argument to provide progressively more detailed control over the result. Thus, for EvA , the argument F may be a single number, a pair of numbers, or a vector of length 2x~l-M,p J 4. In general, a pair of numbers is used to control the result: the first determines the total width of a number field, and the second sets the precision . For decimal form the precision is specified as the HH APL Language number of digits to the right of the decimal point, and for scaled form it is specified as the number of digits in the multiplier. The form to be used is determined by the sign of the precision indicator, negative numbers indicating scaled form. Thus: negative 3 2 pO+A 12 . 34 _0 0.26 i?«-9 2fA S+9 ~2<fA 34.567 12 "123. 45 3 24 pD«-12 3fA 12.340 "34.567 .000 12.000 .260 "123.450 12.34 _.00 .26 3 18 pQf-5 1.2501 _0 .0500 2.65 01 3 18 34.57 12 .00 "123. 45 5501 2501 2502 pD*-6 Of A 12 "35 12 123 3 12 pD«-7 ~1*A 1501 ~3EQ1 0E00 1E01 ~35~01 ~±E02 3 14 If the width indicator of the control pair is zero, a field width is chosen such that at least one space will be left between adjacent numbers. If only a single control number is used, it is treated like a number pair with a width indicator of zero: p0-*-2vA 12.34 "34.57 _.00 12.00 .26 "123.45 3 16 pQ-f-0 2vA 12.34 "34.57 .00 12.00 ".26 "123.45 3 16 pD+-~2<M 1.2501 "3.5501 0.050 1.2501 ~2.65~01 "1.2502 3 18 pCH-0 ~2VA 1.2501 ~3. 5E01 0.0500 1.2501 ~2.65 01 "1.2502 3 18 Each column of an array can be individually composed by a left argument that has a control pair for each: pD«-0 2 2wA 12.34 "34.57 .00 12.00 ".26 "123.45 3 15 pQ-<-6 2 12 ~3Ti4 12.34 "3.46S01 .00 1.20501 ".26 "1.23502 3 18 pQ«-8_3 2JA 12.340 34.57 .000 12.00 ".260 "123.45 3 16 pQf-8 ~2Ti4 12 "3.5501 1.2501 "1.2502 3 17 6283304050 12 4t ,A 12.34 34.567 12 "123.4500 The format function applied to an array of rank greater than two applies to each of the planes defined by the last two axes. For example : Section 3: Primative Functions and Operators 45 L«-2 = ?2 2 5p2 L 4 1TL 110 1 1.01.0 0.00.01.0 1110 1 i.o 1-0 1 -° °-° 1 -° 10 10 1.00.00.01.00.0 ooooo 0.00.00.00.00.0 Tabular displays incorporating row and column headings, or other information between columns or rows, are easily configured using the format function together with catenation. For example: ROWHEADS*-k Zq'JANAPRJULOCT' YEARS+71-HS TABLE*-. 001x~4£5+?4 5p8£5 (• » ,il^ROWHEADS), (.2^9 OvYEARS) , [ 1 ] 9 If TABLE 72 73 7 4 75 _76 JAN 318.13 "351.55 _ 3.62 "144.77 4.82 APR "327.41 "341.00 "92.69 331.05 28.44 JUL "359.93 216.16 _299..71 150.77 103.64 OCT 180.33 310.86 154.94 10.62 276.79 There are obvious restrictions on the left argument of format, since the width of a field must be large enough to hold the requested form, and if the specified width is inadequate the result will be a DOMAIN error. However, the width need not provide open spaces between adjacent numbers. For example, boolean arrays can be tightly packed: 1 0?2=?4 4p2 1001 0000 1101 0111 The following formal characteristics of the format function need not concern the general user, but may be of interest in certain applications : The least width needed for a column of numbers C with precision P is RMv/f?<o) + (~PeO ~l) + ( |P) + (4,("/0,(i?*0) + L10®|i?+i?=0)[l+P2:0], where S is the rounded value of C given by i?«-(L . 5 + C*io* I P)*10* I P. The expressions (MvA) ,N*B and (M,N)vA,B are equivalent if M and N are full control vectors, that is, if ( ( P A/)=2x"l+ P A ) A(ptf)=2x 1+pB. If 2 = pA7, then (MjA) ,MjB and MvA.B are equivalent. 46 APL Language SECTION 4 : SYSTEM FUNCTIONS AND SYSTEM VARIABLES Although the primitive functions of APL deal only with abstract objects (arrays of numbers and characters), it is often desirable to bring the power of the language to bear on the management of the concrete resources or the environment of the system in which APL operates. This can be done within the language by identifying certain variables as elements of the interface between APL and its host system, and using these variables for communication between them. While still abstract objects to APL, the values of such system variables may have any required concrete significance to the host system. In principle all necessary interaction between APL and its environment could be managed by use of a complete set of system variables, but there are situations where it is more convenient, or otherwise more desirable, to use functions based on the use of system variables which may not themselves be made explicitly available. Such functions are called, by analogy, system functions . System variables and system functions are denoted by distinguished names that begin with a quad (Q) . The use of such names is reserved for the system and cannot be applied to user-defined objects. They cannot be copied, grouped, or erased; those that denote system variables can appear in function headers, but only to be localized (see Section 6) . Within APL statements, distinguished names are subject to all the normal rules of syntax. SYSTEM FUNCTIONS Like the primitive abstract functions of APL, the system functions are available throughout the system, and can be used in defined functions. They are monadic or dyadic, as appropriate, and have explicit results. In most cases they also have implicit results, in that their execution causes a change in the environment. The explicit result always indicates the status of the environment relevant to the possible implicit result. Altogether, 13 system functions are provided. Six of these are concerned with the management of the shared-variable facility and are described in Section 5. The other seven are given in Figure 4.1, and are described here. CANONICAL REPRESENTATION The canonical representation of a defined function as defined in Section 6 is obtained as a result of applying the system function OCR to the character array representing the name of the function. Applied to any argument which does not represent the name of an unlocked defined function it yields a matrix of dimension o by o. Possible error reports for OCR are 'RANK error if the argument is not a vector or a scalar, or DOMAIN error if the argument is not a character array. The use of OCR is further described in Section 6. FUNCTION ESTABLISHMENT The definition of a function can be established or fixed by applying the system function OFX to its character representation. The function OFX produces as an explicit result the array of characters which represents the name of the function being fixed, while replacing any existing definition of a function with the same name. Section 4: System Functions and System Variables 47 FUNCTION UCR A UFX M OEX A DNL N REQUIREMENTS RANK LENGTH l>pp4 2 = ppM 2>ppA l>ppff A DNL N DNC A DDL S lappiV 2£ppM lappS lip. 5 DOMAIN Array of characters. Matrix of characters. Array of characters. A/Nel 2 3 A/flel 2 3 Elements of A must be alphabetic. Array of characters. EFFECT ON ENVIRONMENT None. Fix (establish) definition of the function represented by M, unless its name is already in use for an object other than function which is not halted. Expunge (erase) objects named by rows of A, except groups, labels, or halted functions. None. None. None. Numeric value. None, but requires S seconds to complete. EXPLICIT RESULT Canonical representation of object named by A. The re- sult for anything other than an unlocked defined function is of size 0. A vector representing the name of the function estab- lished, or the scalar row index of the fault which prevented establishment. A boolean vector whose Ith element is 1 if the Ith name is now free. A matrix of rows (in acci- dental order) representing names of designated kinds in the dynamic environment: 1, 2, 3 for labels, varia- bles, functions. As for the monadic form, except that only names be- ginning with letters in A will be included. A vector giving the usage of the name in each row of A : name is available 1 label 2 variable 3 function 4 other Scalar value of actual delay. Figure 4.1: System Functions An expression of the form DFX M will establish a function if both the following conditions are met: 1. M is a valid representation of a function. Any matrix which differs from a canonical matrix only in the addition of non- significant spaces (other than rows consisting of spaces only) is a valid representation. 2. The name of the function to be established does not conflict with an existing' use of the name for a halted function (defined in Section 7) or for a label, group, or variable. If the expression fails to establish a function then no change occurs in the workspace and the expression returns a scalar index of the row in the matrix argument where the fault was found. If the argument of UFX is not a matrix a RANK error will be reported, and if it is not a character array a DOMAIN error will result. EXPUNGE Certain name conflicts can be avoided by using the expunge function OEX to dynamically eliminate an existing use of a name. Thus OEX •Pejf?' will erase the object PQR unless it is a label, a group, or a 48 APL Language halted function. The function returns an explicit result of l if the name is now unencumbered, and a result of o if it is not, or if the argument does not represent a well- formed name. The expunge function applies to a matrix of names and then produces a logical vector result. QEX will report a RANK error if its argument is of higher rank than a matrix, or a DOMAIN error if the argument is not a character array. A single name may also be presented as a vector or scalar. NAME LIST The dyadic function QNL yields a character matrix, each row of which represents the name of an object in the dynamic environment. The right argument is an integer scalar or vector which determines the class of names produced as follows: 1, 2, and 3 respectively invoke the names of labels, variables, and functions. The left argument is a scalar or vector of alphabetic characters which restricts the names produced to those with an initial letter occurring in the argument. The ordering of the rows of the result is fortuitous . The monadic function QNL behaves analogously with no restriction on initial letters. For example, QNL 2 produces a matrix of all variable names, and either of QNL 2 3 or QNL 3 2 produces a matrix of all variable and function names. The uses of 'QNL include the following: In conjunction with QEX, all the objects of a certain class can be dynamically erased; or a function can be readily defined that will clear a workspace of all but a preselected set of objects. In conjunction with QCR , functions can be written to automatically display the definitions of all or certain functions in the workspace, or to analyze the interactions among functions and variables. The dyadic form of QNL can be used as a convenient guide in the choice of names while designing or experimenting with a workspace. NAME CLASSIFICATION The monadic function QNC accepts a matrix of characters and returns a numerical indication of the class of the name represented by each row of the argument. A single name may also be presented as a vector or scalar. The result of QNL is a suitable argument for QNC, but other character arrays may also be used, in which case the possible results are integers ranging from to 4. The significance of l, 2, and 3 are as for QNL} a result of signifies that the corresponding name is available for any use; a result of u signifies that the argument is not available for use as a name. The latter case may arise because the name is in use for denoting a group, or because the argument is a distinguished name or not a valid name at all. DELAY The delay function, denoted by QDL , evokes a pause in the execution of the statement in which it appears. The argument of the function determines the duration of the pause, in seconds, but the accuracy is limited by possible contending demands on the system at the moment of release. Moreover, the delay can be aborted by a strong Section 4: System Functions and System Variables 49 interrupt. The explicit result of the delay function is a scalar value equal to the actual delay. If the argument of DDL is not a scalar with a numerical value, a RANK or DOMAIN error will be reported. Generally speaking, the delay function uses only a negligible amount of computer time (as opposed to connect time) . It can therefore be used freely in situations where repeated tests may be required at intervals to determine whether an expected event has taken place. This is useful in work with shared variables (as in the function OFFER given as an example in Section 5) , as well as in certain kinds of interactions between users and programs. SYSTEM VARIABLES System variables are instances of shared variables , which are treated in Section 5. The characteristics of shared variables that are most significant here are these: 1. If a variable is shared between two processors, the value of the variable when used by "one of them may well be different from what that processor last specified, and 2. each processor is free to use or not use a value specified by the other, according to its own internal workings. System variables are shared between a workspace and the APL processor. Sharing takes place automatically each time a workspace is activated and, when a system variable is localized in a function, each time the function is used. The system variables are listed in Figure 4.2, which gives their significance and use. Two classes can be discerned: 1. Comparison tolerance, index origin, latent expression, random link, printing precision, and printing width. In these cases the value specified by the user (or available in a clear workspace) is used by the APL processor during the execution of operations to which they relate. If this value is inappropriate, or if no value has been specified after localization, an IMPLICIT error will be evoked at the time of execution. 2. Account information, atomic vector, line counter, time stamp, terminal type, user load, and work area. In these cases localization or setting by the user are immaterial. The APL processor will always reset the variable before it can be used again. The APL statement represented by the latent expression is automatically executed whenever the workspace is activated. Formally, DLX is used as an argument to the execute function (*QLX) , and any error message will be appropriate to the use of that function. Common uses of the latent expression include the form QLX+'G* used to invoke an arbitrary function G, the form: QLX+ " ' FOR NEW FEATURES IN THIS WS ENTER: NEW" used to print a message upon activation of the workspace, and the form DLX-*- , -*ULC t used to automatically restart a suspended function. The variable DLX may also be localized within a function and respecified therein to furnish a different latent expression when the function is 50 APL Language NAME PURPOSE VALUE IN CLEAR WS MEANINGFUL RANGE uct Comparison tolerance: used in monadic f L, dyadic << = £>*£ i 1£~13 0-1 DIO Index origin: used in indexing and in ? i i H QP-^ 1 1 ULX Latent expression executed on activation of workspace i t characters DPP Printing precision: affects numeric output and monadic v 10 116 Upw Printing width: affects all but bare output and error reports (system dependent) URL Random link: used in ? 7*5 i. 1 + 2*31 OAI Account information: identification, computer time, connect time, keying time (all times in milliseconds and cumulative during session) UAV Atomic vector ULC Line counter: statement numbers of functions in execution or halted, most recently activated first \0 UTS Time stamp: year, month, day (of month) , hour (on 24-hour clock), minute, second, millisecond DTT Terminal type: 1 for Selectric, 2 for PTTC/BCD, 3 for 1050 UUL User Load UWA Working area available (in bytes) Figure 4.2: System Variables suspended. [13 [2] [3] For example : QLX+ ' F • V F;ULX ULX*-'+ULC,pU<r"WE CONTINUE FROM WHERE WE LEFT OFF'" 'WE NOW BEGIN LESSON 2' DRILLFUNCTION V )SAVE ABC On the first activation of workspace ABC, the function F would be automatically invoked; if it were later saved with F halted, subsequent activation of the workspace would automatically continue execution from the point of interruption. The atomic vector UAV is a 256-element character vector, containing all possible characters. Certain elements of UAV may be terminal control characters, such as carrier return or linefeed, but other elements of UAV may neither print nor exercise control. The indices of any known characters can be determined by an expression such as UAVx >ABCABC X . Section 4: System Functions and System Variables 51 SECTION 5: SHARED VARIABLES Two otherwise independent concurrently operating processors can communicate , and thereby be made to cooperate, if they share one or more variables. Such shared variables constitute an interface between the processors, through which information may be passed to be used by each for its own purposes. In particular, variables may be shared between two active APL workspaces, or between an APL workspace and some other processor that is part of the overall APL system, to achieve a variety of effects including the control and utilization of devices such as printers, card readers, magnetic tape units, and magnetic disk storage units. In use in an APL workspace, a shared variable may be either global or local, and is syntactically indistinguishable from ordinary variables. It may appear to the left of an assignment, in which case its value is said to be set , or elsewhere in a statement, where its value is said to be used . Either form of reference is an access . At any instant a shared variable has only one value, that last assigned to it by one of its owners. Characteristically, however, a processor using a shared variable will find its value different from what it might have set earlier. A given processor can simultaneously share variables with any number of other processors. However, each sharing is bilateral; that is, each shared variable has only two owners. This restriction does not represent a loss of generality in the systems that can be constructed, and commonly useful arrangements are easily designed. For example, a shared file can be made directly accessible to a single control processor which communicates bilaterally with (or is integral with) the file processor itself. In turn, the central processor shares variables bilaterally with each of the using processors, controlling their individual access to the data, as required. It was noted in Section 4 that system variables are instances of shared variables in which the sharing is automatic. It was not pointed out, however, that access sequence disciplines are also imposed on certain of these variables, although one effect of this was noted; namely, variables like the time stamp accept any value specified, but continue to provide the proper information when used. The discipline that accomplishes this effect is an inhibition against two successive accesses to the variable unless the sharing processor (the system) has set it in the interim. When ordinary, "undistinguished", variables are to be shared, explicit actions are necessary to effect the sharing and establish a desired access discipline. six system functions are provided for these purposes: three for the actual management and three to provide related information. These are summarized in Figure 5.1. OFFERS A single offer to share is of the form p USVO N, where p is the identification of another processor and N is a character vector representing a pair of names. The first of this pair is the name of the variable to be shared, and the second is a surrogate name which is offered to match a name offered by the other processor. The name of the variable may be its own surrogate, in which case only the one name need be used, rather than two. For example, the three sets of actions shown below all have the same effect, which is to share one variable between two processors 12 34 and 567 8, the variable being known to the former as 52 APL Language FUNCTION REQUIREMENTS [1] EFFECT ON ENVIRONMENT EXPLICIT RESULT RANK LENGTH DOMAIN P'QSVO N 22ppff (x/pP)el ,~l+pff Pe~l+i2*31 [2] Tenders offer to processor P if first (or only) name of a pair is not previously offered and not already in use as the name of an ob- ject other than a variable. The offer is general (to anyone) if 0=P. Degree of coupling now in effect for the name pair. Dimension: x/ 1+pff. DSVO N 2!>ppff None. [2] None. Degree of coupling now in effect for the name pair. Dimension: x/~i+pff. C OSVC N 2>ppff 2>ppC (l>ppC) Al=x/pC or (pC) = ( l + pJV),4 A/CeO 1 [2] Sets access control. New setting of access con- trol. Dimension: ( l+pff),4. QSVC N 2!>ppff None. [2] Existing access control. USVR N 2>ppff None. [2] Retracts offer (ends shar- ing) . Degree of coupling before this retraction. Dimension: x/'UpN. QSVQ P l>ppP 1*P,P Pe - l+i2*31 None. If 0=pP: Vector of identi- fications of processors making offers to this user. If l=x/pP: Matrix of names offered by processor P but not yet shared. NOTES: 1. If a requirement is not met the function is not executed and a corresponding error report is printed. 2. Each row of N (or N itself if 22ppff) must represent a name or pair of names. If a pair of names is used for an offer (dyadic DSVO), either the pair, or the first name only, can be used for the other functions. Figure 5.1; Functions for the Management of Sharing ABC, and to the latter as Q. User 12 34 User 5 67 8 5678 QSVO 'ABC Y« 1 1234 DSVO 'Q Y' 5678 DSVO 'ABC Q* 1234 DSVO •«' 5678 DSVO MAC 1 12 34 DSVO iQ ABC 1 The surrogate names have no effect other than to control the matching, making it possible for one processor to operate with no direct knowledge of, or concern with, the variable name used by the other. The same surrogate can be used in a succession of offers to the same processor, in which case they are matched in sequence by appropriate counter-offers. The same surrogate may also be used for offers to any number of other processors at the same time. However, since a variable may be offered to (or shared with) only one other processor at a time, each coincident use of a particular surrogate name must be associated with a different variable name. Section 5: Shared Variables 53 The explicit result of the expression P DSVO N is the degree of coupling of the name or name pair in N: zero if no offer has been made, one if an offer has been made but not matched, two if sharing is completed. An offer to any processor (other than the offering processor itself) increases the coupling of the name offered if the name has zero coupling and is not the name of a label, function, or group. An offer never decreases the coupling. The monadic function DSVO does not affect the coupling of the name represented by its argument, but does report the degree of coupling as its explicit result. If the degree of coupling is one or two, a repeated offer has no further implicit result and either monadic or dyadic DSVO may be used for inquiry. Advantage is taken of this in the following example of a defined function for offering a name (to be entered on request) to a processor P for a period of T seconds: Z+P OFFER T;I;Q m«- ' NAME : ' ■+( • <K.=Q+a)/z+-i*-o Il:-v(2 = Zf-P DSVO Q)/L2 ■+(TzI+I+l + OxDDL 1)/L1 'NO DEAL* + L2: 'ACCEPTED' V If the arguments of DSVO fail to meet any of the basic requirements listed in Figure 5.1, the appropriate error report is evoked and the function is not executed. If a user attempts to share more variables than the quota allotted to him by those responsible for the general management of the system the error report will be INTERFACE QUOTA EXHAUSTED, and if, for any reason, the shared variable facility itself is not available the report will be NO SHARES. An offer to a processor will be tendered, whether or not the processor happens to be available. The value of a shared variable when sharing is first completed is determined thus: if both owners had assigned values beforehand, the value is that assigned by the first to have offered; if only one owner had, that value obtains; if neither had, the variable has no value. Names used in sharing are subject to the usual rules of localization. A set of offers can be made by using a vector left argument (or a scalar or one-element vector which is automatically extended) and a matrix right argument, each of whose rows represents a name or name pair. The offers are then treated in sequence and the explicit result is the vector of the resulting degrees of coupling. If the quota of shared variables is exhausted in the course of such a multiple offer, none of the offers will be tendered. An offer made with zero as left argument is a general offer, that is, an offer to any processor. A general offer will be matched only with a counter-offer which is not general, that is, one that explicitly identifies the processor making the general offer. The processor identification associated with a user is the user's, sign-on number. Auxiliary processors are usually identified by numbers between 1 and 1000. 54 APL Language ACCESS CONTROL Consider the following simple example of sharing the variable 7 between two users 1234- and 567 8: User 1234 User 5 67 8 5678 QSVO '7* V+-5 V 123"+ QSVO '7' 7-*-3x7*2 75 The relative sequence of events in the two workspaces, after sharing, is significant; for example, had the use of 7 by 1234 in the foregoing example preceded the setting by 567 8, the resulting value would have been 5 rather than 7 5 . In most practical applications it is important to know that a new value has been assigned between successive uses of a shared variable, or that use has been made of an assigned value before a new one 'is set. Since, as a practical matter, this cannot be left to chance, an access control mechanism is embodied in the shared variable facility. The access control operates by inhibiting the setting or use of a shared variable by one owner or the other, depending upon the access state of the variable, and the value of an access control matrix which is set jointly by the two owners, using the dyadic form of the system function QSVC . If, in the example above, one user (say 567 8) had followed his offer to share 7 by the expression l l l 1 QSVC '7', then the desired sequence would have been enforced. That is, the use of 7 by 5678 would be automatically delayed until 7 is set by 1234, and the use by 1234 would be delayed until 7 is set by 5678. The delay occasioned by the inhibition of any access uses only a negligible amount of computer time. Interruption by a strong interrupt signal during the period of delay aborts the access and unlocks the keyboard . Figure 5.2 shows variable, the possible inhibitions imposed by ACM is associated with second with its use. indicated by the zeros the access state shown Figure 5.2 to validate the three access states possible for a shared transitions between states, and the potential the access control matrix, ACM. The first row of setting of the variable by each owner, and the The permissible operations for any state are in ACMaasm, where ASM is the representation of in the figure. This can be confirmed by using each of the following statements : If ACMLl -,l] = l r then two successive sets by A require an intervening access (set or use) by B. If ACMll;2l=l, then two successive sets by B require an intervening access by A. If ACMi2;ll=li then two successive uses by A require an intervening set by B. If ACML2;2l=l, then two successive uses by B require an intervening set by A. The value of the access state representation is not directly available to a user, but the value of the access control matrix is given by the monadic function QSVC. For a shared variable 7 the result of the Section 5: Shared Variables 55 Legend : SA SB UA UB Denote set or use by A ACM: Access Control Matrix ASM: Access State Matrix or B. A one in an element of ACM inhibits the associated access. Allowable accesses are given by the zeroes in ACM^ASM. Access control vectors as seen by A and B, respectively, are ,ACM and AACM. The access state matrix represents the last access : ones occur in the last row if it is not a set, and in a column if it is, the first column if set by A and the last if set by B. Figure 5.2: Access Control of a Shared Variable 56 APL Language Access Control Vector as seen by Comments A B No constraints. Half -duplex. Ensures that each use is preceded by a set by partner. Half-duplex. Ensures that each set is preceded by an access by partner. Reversing half-duplex. Maximum constraint. Simplex. Controlled communication from B to A. (For card reader, etc.) 11 110 1111 110 11 110 1111 10 1 Figure 5.3: Some Useful Settings for the Access Control Vector expression USVC '7' executed by user A is the access control vector ,ACM (the four-element ravel of ACM). However, if user B executed the same expression he would obtain the result ,<$>ACM. The reason for the reversal is that sharing is symmetric: neither owner has precedence over the other, and each sees a control vector in which the first one of each pair of control settings applies to his own accesses. This symmetry is evident in Figure 5.2; if it were redrawn to interchange the roles of A and B the control matrix would be the row-reversal of the matrix shown. The setting of the access control matrix for a shared variable is determined in a manner which maintains the functional symmetry. An expression of the form L USVC 'V executed by user A assigns the value of the logical left argument L to a four-element vector which, for the purposes of the present discussion, will be called QA. Similar action by user B sets QB . The value of the access control matrix is determined as follows: ACM*-(2 2pQA)v§2 2pQB Since ones in ACM inhibit the corresponding actions, it is clear from this expression that one -user can only increase the degree of control imposed by the other (although he can, by using USVC with a left argument of zeros, restore the control to that minimum level at any time) . Access control can be imposed only after a variable is offered, either before or after the degree of coupling reaches two. The initial values of QA and QB when sharing is first offered are zero. The access state when a variable is first offered (degree of coupling is one) is always the initial state shown in Figure 5.2. If the variable is set or used before the offer is accepted, the state changes accordingly. Completion of sharing does not change the access state. Figure 5.3 lists a number of settings of the access control vector which are of common practical interest. Any one of them can be represented by a simplification of Figure 5.2 obtained by omitting the control matrix and deleting the lines representing those accesses which are inhibited in the particular case. For example, with maximum constraints all the inner paths would be removed from the figure. Section 5 : Shared Variables 57 A group of N access control matrices can be set at once by applying the function OSVC to an if by t matrix left argument and an tf-rowed matrix right argument of names. The explicit result is an N by u- matrix giving the current values of the (ravels of) control matrices. When control is being set for a single variable the left argument may be a single 1 or. if all inhibits or none are intended. RETRACTION Sharing offers can be retracted by the monadic function DSVR applied to a name or a matrix of names. The explicit result is the degree (or degrees) of coupling prior to the retraction. The implicit result is to reduce the degree of coupling to zero. Retraction of sharing is automatic if the connection to the computer is interrupted or if the user signs off or loads a new workspace. Sharing of a variable is also retracted by its erasure or, if it is a local variable, upon completion of the function in which it appeared. The nature of the shared-variable implementation is often such that the current value of a variable set by a partner will not be represented within a user's workspace until actually required to be there. This requirement obtains when the variable is to be "used, when sharing is terminated, or when a SAVE command is issued (since the current value of the variable must be stored) . Under any of these conditions it is possible for a WS FULL error to be reported. In all cases the prior access state remains in effect and the operation can be retried after corrective action. INQUIRIES There are three monadic inquiry functions which produce information concerning the shared variable environment but do not alter it; the functions QSVOand USVC already discussed, and the function OSVQ. A user who applies the latter function to an empty vector obtains a vector result containing the identification of each user making any sharing offer to him. A user who applies the function OSVQ to a non-empty argument obtains a matrix of the names offered to him by the processor identified in the argument. This matrix includes only those names which have not been accepted by counter-offers. The expression (.Q*OSVO AO/Cl] M+ONL 2 can be used to produce a character matrix whose rows represent the names of all shared variables in the dynamic environment. 58 APL Language SECTION 6: FUNCTION DEFINITION There are three ways in which a defined function can be established in an APL workspace: 1. It can be copied from a stored workspace using a system command, as described in Section 8. 2. It can be established in execution mode, using the system function DFX, either in direct keyboard entry or in the course of execution of another defined function. 3. It can be established in function definition mode. Regardless of which facility has been used for establishing a function, its definition can be displayed or modified in either the function definition mode, in which certain editing capabilities are built-in, or by the combined use of the system functions OCR and QFX. CANONICAL REPRESENTATION AND FUNCTION ESTABLISHMENT The character representation of a function is a character matrix satisfying certain constraints: the first row of the matrix represents the function header and must be one of the forms specified below in the section on function headers. The remaining rows of the matrix, if any, constitute the function body , and may comprise any sequence of characters. If the character representation satisfies additional constraints such as no redundant spaces and left justification of the non-blank character in each row, then it is said to be a canonical representation . Applying OCR to the character array representing the name of an already established function will produce its canonical representation. For example, if OVERTIME is an available function: DEF+OCR 'OVERTIME* DEF PAI+R OVERTIME H;TIME TIME+0\H-H0 PAY+R*1.5xTIME pDEF 3 21 The function QCR applied to any argument which does not represent the name of an unlocked defined function yields a matrix of shape 0. Error reports for QCR are RANK error if the argument is not a vector or a scalar, or DOMAIN error if the argument is not a character array. The use of OCR does not change the status of the function OVERTIME, which remains established and can be used for calculations. Thus: 7 5 8 OVERTIME 3 5 40 4-5 60 If OVERTIME should be expunged: DEX 'OVERTIME* Section 6 : Function Definition 59 it is no longer available for use : 7 5 8 OVERTIME 3 5 40 45 SYNTAX ERROR 7 5 8 OVERTIME 3 5 40 4 5 A The function can be re-established by UFXi QFX DEF OVERTIME The function QFX produces as its explicit result the vector of characters which represents the name of the function being fixed, while replacing any existing definition of a function with the same name. The function OVERTIME can now be used again: 7 5 8 OVERTIME 3 5 40 4 5 60 As noted in Section 4, an expression of the form UFX M will establish a function if the following conditions are met: 1. M is a valid representation of a function. Any matrix which differs from a canonical matrix only in the addition of non-significant spaces (other than rows consisting of spaces only) is a valid representation. 2. The name of the function to be established does not conflict with an existing use of the name for an executing or halted function or for a label, group, or variable. If the expression fails to establish a function then no change occurs in the workspace and the expression returns a scalar index of the row in the matrix argument where the fault was found. If the argument of DFX is not a matrix a RANK error will be reported, and if it is not a character array a DOMAIN error will result. THE FUNCTION HEADER The v alence of a function is defined as the number of explicit arguments which it takes. A defined function may have a valence of zero, one, or two, and may yield an explicit result or not. These cases are represented by six forms of header as follows: Type Valence Result No Result Dyadic 2 R+-A F B A F B Monadic i r+f B F B Niladic R+F F The names used for the arguments of a function become local to the function, and additional local names may be designated by listing them after the function name and argument, separated from them and from each other by semicolons; the name of the function is global . The significance of these distinctions is explained below. Except that the function name itself may be repeated in the list of local names, a name may not be repeated in the header. It is not obligatory either for the arguments of a defined function to be used within the body, or for the result variable to be specified in the course of function execution. 60 APL Language LOCAL AND GLOBAL NAMES In the execution of a defined function it is often necessary to work with intermediate results or temporary functions which have no significance either before or after the function is used. The use of local names for these purposes, so designated by their appearance in the function header, avoids cluttering the workspace with a multitude of objects introduced for such transient purposes, and allows greater freedom in the choice of names. Names used in the function body, and not so designated, are said to be global to that function. A local name may be the same as that for a global object, and any number of names local to different functions may be the same. During the execution of a defined function, a local name will temporarily exclude from use a global object of the same name. If the execution of a function is interrupted (leaving it either suspended , or pendent (See Section 7) , the local objects retain their dominant position, during the execution of subsequent APL operations, until such time as the halted function is completed. However, system commands and the del form of function definition (see below) continue to reference global objects under these circumstances. The localization of names is dynamic, in the sense that it has no effect except when the defined function is being executed. Furthermore, when a defined function uses another defined function during its execution, a name localized in the first (or outer) function continues to exclude global objects of the same name from the purview of the second (or inner) function. This means that a name localized in an outer function has the significance assigned to it in that function when used without further localization in an inner function. The same name localized in a sequence of nested functions has the significance assigned to it at the innermost level of execution. The shadowing of a name by localization is complete, in the sense that once a name has been localized its global and outer values are nullified, even if no significance is assigned to it during execution of the function in which it is localized. BRANCHING AND STATEMENT NUMBERS Statements in a function are normally executed successively, from top to bottom, and execution terminates at the end of the last statement in the sequence. This normal order can be modified by branches . Branches are used in the construction of iterative procedures, in choosing one out of a number of possible continuations, or in other situations where decisions are made during the course of function execution. To facilitate branching, the successive statements in a function definition have reference numbers associated with them, starting with the number one for the first statement in the function body and continuing with successive integers, as required. Thus, the expression +4 denotes a branch to the fourth statement in the function body, and when executed causes statement t to be executed next, regardless of where the branch statement itself occurs. (In particular -+-M- may be statement 4, in which case the system will simply execute this "tight loop" indefinitely, until interrupted by an action from the keyboard. This is a trap to be avoided.) A branch statement always starts with the branch arrow (or right arrow ) on the left, and this can be followed by any expression. For the statement to be effective, however, the expression must evaluate to an integer, to a vector whose first element is an integer, or to an empty vector; any other value results in a DOMAIN or RANK error. If the Section 6: Function Definition 61 expression evaluates to a valid result, then the following rules apply: 1 . If the result is an empty vector the branch is vacuous and execution continues with the next statement in the function if there is one, or else the function terminates. 2. If the result is the number of a statement in the function then that statement is the next to be executed. 3. If the result is a number out of the range of statement numbers in the function, then the function terminates. The number o and all negative integers are outside of the range of statement numbers for any function. Since zero is often a convenient result to compute, and it is not the number of a statement in the body of any function, it is often used as a standard value for a branch intended to end the execution of a function. It should be noted that in the function definition mode described below, zero is used to refer to the header. This has no bearing on its use as a target for a branch. An example of the use of a branch statement is shown in the following function, which computes the greatest common divisor of two scalars: Z+M GCD N Z+M M+M\N N+Z -*(0*M)/1 The compression function in the form U/V gives V if U is equal to one, and an empty vector if U is equal to zero. Thus, the fourth statement in GCD is a branch statement which causes a branch to the first statement when the condition q*m is true, and a branch with an empty vector argument, that is, normal sequence, when the condition is false. In this case, there is no next statement and so execution of the function ends. LABELS If a statement occurring in the body of a function definition is prefaced by a name and a colon, then the name is assigned a value equal to the statement number. A name used in this way is called a label . Labels are used to advantage when it is expected that a function definition may be changed for one reason or another, since a label automatically assumes the new value of the statement number of its associated statement as other statements are inserted or deleted. The name of a label is local to the function in which it appears, and must be distinct from other label names and from the local names in the header. A label name may not appear immediately to the left of a specification arrow. In effect it acts like a (local) constant. COMMENTS The lamp symbol pi (the cap-null) signifies that what follows it is a comment, for illumination only and not to be executed; it may occur only as the first character in a statement. 62 APL Language FUNCTION EDITING - THE V FORM The functions QCR and QFX together form a basis for establishing and revising functions. Convenient definition editing with them, however, requires the use of prepared editing functions which must be defined, stored in a library, and explicitly activated when needed. The del form described here provides an alternative facility for function entry and revision which is always present for use. When the user enters the del character (v) followed by the name of a defined function, the system responds by displaying [tf+1] , where N is the number of statements in the function. It is now possible to: add, insert, or replace statements replace the header modify the header or a statement delete a statement display all or part of the definition A new function is started by entering the desired header on the same line as the opening V. Once the function definition mode has thus been entered, the treatment of a new function is identical to that for a function already defined. ADDING A STATEMENT If the response to the display of statement number [tf+1] is a statement, it is accepted as a line added at the end of the definition. The system response is the display [W+2] . Additional statements may continue to be added to the definition in this manner. If an empty statement is entered, the system will re-display the line number in brackets. INSERTING OR REPLACING A STATEMENT If the response to the statement number displayed by the system is IN] , where N is any positive number with or without a fractional part, the system will display INI . A statement entered will replace an existing statement N. The system continues by displaying the next appropriate number. For example, if the statement number entered was [3] , the next number displayed will be [4] ; if [3.02] , then [3.03] ; if [3.29] then [3.3] , and so forth. A statement may be submitted with line number [#]; it will be inserted or will replace an existing statement in the manner described. The response of the system in this case is to display the next statement number. REPLACING THE HEADER If the user enters [0] , the system responds by displaying [0] . The user may now enter any legal header, which will replace the existing header. Following this, the system displays [1] . The entire operation may be carried out by entering [0] and, on the same line, the header. DELETING A STATEMENT One or more statements may be deleted by entering in brackets a delta followed by one or more statement numbers, for example, [A2 7 3]. The response of the system is to display the statement number that follows the last number in the list. In the example, the response will be [4]. Section 6: Function Definition 63 EDITING A STATEMENT OR HEADER Statement N can be modified by the following mechanism: 1. Enter [AW] where M is an integer. The header is referred to by using o for N. 2. Statement N or the header is automatically displayed and the cursor stops under position M, which is counted from the left margin. 3. A letter or decimal digit or the symbol / may be typed under any of the positions in the display. Any other characters typed in this mode are ignored. The ordinary rules for editing before entry (such as backspace and linefeed) apply. 4. The line is re-displayed. Each character understruck by a / is deleted, each character understruck by a digit K is preceded by K added spaces, and each character understruck by a letter is preceded by 5*R spaces, where R is the position of the letter in the alphabet. For example, the letter C will produce 15 spaces. Finally, the cursor moves to the first injected space and awaits the typing of modifications in the usual manner . The final effect is as if the entry had been - made entirely from the keyboard; in particular, a completely blank sequence leaves the line unchanged. If a statement number itself is changed from N to P during the editing procedure the statement affected is determined by the new statement number P; hence statement N remains unchanged. This permits statements to be moved, with or without modification. If an attempt to display a line would exceed the printing width (determined by DPW) this form of editing is not applicable. Such a condition may arise if the line is too long to start with, or if too many spaces have been requested for insertion. ADDING TO A STATEMENT OR HEADER One or more characters can be added to the end of statement N, or statement N can be corrected, by entering [iVDO]. In response, the system displays statement N; the cursor is positioned at the end of the statement, and the keyboard unlocks. The statement may be extended, or modified by using the normal revision procedures for entry. In response, the system displays the next statement number and awaits entry. The header may be modified in this way by entering [0[]0]. FUNCTION DISPLAY The canonical representation of a function includes the header and body displayed as a character matrix. The V form permits display of a canonical representation modified as follows: 1. Labelled lines and comments are offset one space to the left. 2. Statement numbers in brackets are appended to the left of the statements. 3. A del character (7) is prefixed to the header, separated by one space. 4. A final line is added, consisting of spaces and a del character, aligned with the del character which prefixes the header. 64 APL Language Shown are the canonical representation and function display of a function for computing the determinant of a matrix: UCR'DET' VDETLOlV Z+DET A;B;P;I V Z+DET A;B;P;I I+QIO [ 1 3 I+QIO Z«-l [2] Z<-1 L:F«-( U[;J])ir/UC;I] [3] L : P-K \A C ;I ] ) i \ I \A C ;I] +(P=I)/LL [4] -*{P=I)/LL AiI,P;l<-AlP,I;l [5] 4[I ,P; l-MLP.I ; ] Z«--Z [6] Z-e--Z LL:Z-e-ZxBfi4[I;J] [7] LL : Z+-ZXB+-4 [ J ; J] + (0 1 v.=Z,l + p4)/0 [8] +(0 1 v.=Z,l + pi4)/0 4 + 1 1 +4-U[;J3*B)°.x4[I; ] [9] 4+1 1 + A- {A [ ;X]tB ) <> . x4 [I ; ] -»-£ [10] ->L ^EVALUATES A DETERMINANT [11] ^EVALUATES A DETERMINANT V The display of a function can be obtained by typing CD]. After the display, the system displays [ff+1] where ff is the number of statements in the function. Statement N can be displayed by typing [ffQ]. After display the system types INI. Entering LQKl causes display of all statements from K onwards. After the display the system displays IN +11 where N is the number of statements in the function. LEAVING TIfE V FORM The del form may be left by typing a V on a line by itself, or as the last character on any entry except one which enters a comment statement. In particular, it can follow a request for display or a function statement, and either can be incorporated in the same entry that both opens and closes the definition mode, as in VDETlQlV or VDETilOl+L ,LV. On leaving the del form, the statements are reordered according to their statement numbers and the statement numbers are replaced by the integers 1, 2, 3, and so on. A function definition can be locked by either opening or closing the definition mode with a del-tilde, V. The use of this is explained in Section 7. Section 6: Function Definition 65 SECTION 7: FUNCTION EXECUTION A defined function may be used like a primitive function, except that it may not be the argument of a primitive operator. In particular, a defined function may be used within its own definition or that of another defined function. When a function is called, or put into use, its execution begins with the first statement, and continues with successive statements except as this sequence is altered by branch instructions . Consider the function OVERTIME: PAY+R OVERTIME H-.TIME TIME^0[^0-H PAY*- Rxl.5*TIME If this function is invoked by a statement such as X OVERTIME I the effect is to assign to the local name R the value of X and to H the value of Y, and then execute the body of the function OVERTIME. Except for having a value assigned initially, the argument variable is treated as any other local variable .and, in particular, may be respecified within the function. A function like OVERTIME, which produces an explicit result, may properly be used in compound expressions. In the OVERTIME function the last value received by PAY in the course of execution is the explicit result of the function. For example: YTDAT 100 200 150 YTDAT+YTDAT+0T+-5 7 6 OVERTIME 3 5 40 4 5 OT 45 YTDAT 100 200 195 PAY, itself, is a local variable and therefore has no significance after the function is executed: PAY VALUE ERROR PAY HALTED EXECUTION The execution of a function F may be stopped before completion in a variety of ways: by an error report, by an attention signal, or by the stop control treated below. When this happens the function is said to be suspended , and its progress can be resumed by entering a branch- statement from the keyboard. Whatever the reason for suspension, the name of the function is displayed, with a statement number beside it. In the case of an error stop or an interrupt the statement itself is also displayed, with an appropriate message and an indication of the point of interruption. Unless a specification appears in the statement to the right of this point, the state of the computation has been restored to the condition obtaining before the statement started to execute . In general, therefore, the displayed number is that of the statement that should be executed next if the function is to continue normally. Resumption of execution at that point can be accomplished by entering a branch to that number specifically, a branch to an empty vector, or a branch to QLC. Entering -*0 , or a branch to another number 66 APL Language outside the range of statement numbers, causes an immediate exit from the function and it is no longer suspended. In the suspended state all normal activities are possible, but names used refer to their local significance, if any. The system is in a condition to execute statements or system commands, resume execution of the function at an arbitrary point, or enter definition mode to work on any function which is not pendent (see below) . In particular, the suspended function can be edited at this point (if it is not itself pendent from a previous use) . STATE INDICATOR Entering the system command )SI causes a display of the state indicator ; a typical display has the following form: )SI Hill * F[2] G[3] This display indicates that execution was halted before completing (perhaps before starting) execution of statement 7 of function H, that the current use of function H was invoked in statement 2 of function F, and that the use of function F was in turn invoked in statement 3 of C. The * appearing to the right of ff[7] indicates that the function H is suspended. The functions G and F are said to be pendent , because their execution cannot be restarted directly, but only as a consequence of function H resuming its course of execution. The term halted is used to describe a function which is either pendent or suspended. Further functions can be invoked when in the suspended state. Thus, if G were now invoked and a further suspension occurred in statement 5 of Q , itself invoked in statement 8 of G, a subsequent display of the state indicator would appear as follows: )SI «L5] * GC8] ff[7] * GC2] F[3] Since the line counter, ULC , holds the current statement numbers of functions that are in process of execution, its value at this point would be the vector 5 8 7 2 3. The sequence from the last to the preceding suspension can be cleared by entering a right arrow (->■) . This behavior is illustrated by continuing the foregoing example as follows! fl[7] G[2] **[3] 7 2 3 )SI ULC Repeated use of •*■ will clear the state indicator completely, and restore ULC to an empty vector. The cleared state indicator displays as a blank line. Section 7: Function Execution 67 STATE INDICATOR DAMAGE If the name of a function occurs in the state indicator list, then erasure of the function or replacement of the function by copying a function with the same name (even another instance of the same function) will make it impossible for the original course of execution to be resumed. In such an event an SI DAMAGE report is given. In addition, some APL systems will give an SI DAMAGE report if a suspended function is edited to change the order of its labels or to modify its header. If an SI DAMAGE report is given for a suspended function, it will not be possible to resume its execution by entering a branch statement, but the function can be invoked anew, with or without prior clearance of the state indicator. In case of SI DAMAGE, display of the state indicator will show the damage, possibly by a blank where the function name should have appeared or by some explicit indicator or both. TRACE CONTROL A trace is an automatic display of information generated by the execution of a function as it progresses. In a complete trace of a function, the number of each statement executed is displayed in brackets, preceded by the function name and followed by the final value produced by the statement. The trace of a branch statement shows a branch arrow followed by the number of the next statement to be executed. The trace is useful in analyzing the behavior of a defined function, particularly during its design. The tracing of a function PROFIT. is controlled by the trace control for PROFIT, denoted by TLPROFIT. If one sets T A PR FIT*- 2 3 5 then statements 2, 3, and 5 will be traced in any subsequent execution of PROFIT. TLPROFIT+xQ discontinues tracing of PROFIT. A complete trace of PROFIT is obtained by ThPROFIT+xN , where N is the number of statements in PROFIT. In general, the trace control for any function is designated by prefixing TA to the function name. STOP CONTROL A function can be caused to execute up to a certain statement and then stop in the suspended state. This is frequently useful in analyzing a function, for example by experimenting with local variables or intermediate results. The stops are set by the stop control in the same manner as the trace. For a function PROFIT, stops before "lines 4 and 12 are executed would be set by entering S&PROFIT+H 12. At each stop, the function name and line number are displayed as described above for suspended functions. To go to the next stopping point after the first, execution must be explicitly restarted by entering an appropriate branch statement. Trace control and stop control can be used in conjunction. Moreover, either of the controls may be set within functions. In particular, they may be set by expressions which initiate tracing or stops as a result of certain conditions that may develop in the course of function execution, such as a particular variable taking on a particular value. They may only be used as the left argument of specification. They may not be used by themselves or as the argument to a function . 68 APL Language LOCKED FUNCTIONS If the symbol ¥ (called del-tilde) is used instead of v to open or close a function definition, the function becomes locked . A locked function cannot be revised or displayed in any way. Any associated stop control or trace control is nullified after the function is locked. A locked function is treated essentially as a primitive, and its inner workings are concealed as much as possible. Execution of a locked function is terminated by any error ocurring within it, or by a strong interrupt. If execution stops the function is never suspended but is immediately abandoned. The message displayed for a stop is DOMAIN error if an error of any kind occured, WS FULL and the like if the stop resulted from a system limitation, or INTERRUPT. Moreover, a locked function is never pendent, and if an error occurs in any function invoked either directly or indirectly by a locked function, the execution of the entire sequence of nested functions is abandoned. If the outermost locked function was invoked by an unlocked function, that function will be suspended; if it was invoked by a keyboard entry the error message will be displayed with a copy of that statement. Similarly, when a weak interrupt is encountered in a locked function, or in any function that was ultimately invoked by a locked function, execution continues normally up to the first interruptable point: either the next statement in an unlocked function that invoked the outermost locked function, or the completion of the keyboard entry that used this locked function. In the latter case, the weak interrupt has no net effect. Locked functions may be used to keep a function definition proprietary, or as part of a security scheme for protecting other proprietary information. They are also used to force the kind of behavior just described, which sometimes simplifies the use of applications . RECURSIVE FUNCTIONS A defined function whose name has not been made local and is used in the body of the function definition is said to be defined recursively . For example, one definition of the greatest common divisor function states that the greatest common divisor of zero and any number N is N; for any other pair of numbers it is the greatest common divisor of the residue of the second number by the first, and the first number. The words "greatest common divisor" are used in the definition. This suggests that a greatest common divisor function GCDR can be written whose canonical representation is: DCR * GCDR ' R+A GCDR B R+B -Ko=4)/o R+(A |B) GCDR A 18 GCDR 45 9 This can be compared to the equivalent function defined iteratively in Section 6. Executing an erroneously defined recursive function will often result in a WS FULL report. The non-trivial execution of a properly defined recursive function may also have this effect because of the very deep nesting of function calls that is often required. Section 7: Function Execution 69 TERMINAL INPUT AND OUTPUT In many significant applications, such as text processing, for example, it is necessary that the user supply information as the execution of the application programs progresses. It is also often convenient, even in the use of an isolated function, to supply information in response to a request, rather then as arguments to the function as part of the original entry. This is illustrated by considering the use of the function CI, which determines the growth of a unit amount invested at periodic interest rate R for number of periods T: OCR' CI 1 A+R CI T A<-(1+R)*T For example, the value of 1000 dollars at 5 per cent for 7 years, compounded quarterly, might be found by: 1000 x (.05*4) CI 7x4 1415.992304 The casual user of such a function might, however, find it difficult to remember which argument of CI is which, how to adjust the rate and period stated in years for the frequency of compounding, and whether the interest rate is to be entered as the actual rate (for example, .05) or as a percentage (for example, 5). An exchange of the following form might be more suitable: INVEST ENTER CAPITAL AMOUNT IN DOLLARS D: 1000 ENTER NUMBER OF TIMES COMPOUNDED IN ONE YEAR □ : 4 ENTER ANNUAL INTEREST RATE IN PERCENT D: 5 ENTER PERIOD IN YEARS D: 7 VALUE IS 1415.992304 It is necessary that each of the entries (1000, 4, 5, and 7) occurring in such an exchange be accepted not as an ordinary entry (which would only evoke the response 1000, etc.), but as data to be used within the function INVEST. Facilities for this are provided in two ways, termed evaluate d input , and character input . A definition of the function INVEST, which uses evaluated input, is as follows: UCR' INVEST' INVEST ;CiR;T;F ' ENTER CAPITAL AMOUNT IN DOLLARS* C*-D 'ENTER NUMBER OF TIMES COMPOUNDED IN ONE YEAR 1 F+0 'ENTER ANNUAL INTEREST RATE IN PER CENT' R+U+FxlOO 'ENTER PERIOD IN YEARS' T-f-FxQ 'VALUE IS ' ,vCxR CI T The function NEWSTOCK in the Introduction (Section 1) is an example of the use of both character input and bare output (discussed below) . 70 APL Language EVALUATED INPUT The quad symbol Q appearing anywhere other than immediately to the left of a specification arrow denotes request for keyboard input as follows: the two symbols D: are displayed, and the keyboard is unlocked on the next line, indented from the left margin. Any valid expression entered at this point is evaluated, and the result substituted for the quad. Suppose F is a function whose definition includes a quad symbol: OCR ' F ' Z-f-F Z-s-l+xQ F D: 3 + 2 20 An invalid entry in response to a request for quad input causes an appropriate error report, after which input is again awaited. For example, entering an expression which has no result produces a value error. Function definition mode (the editing or display of functions, or creation of new functions) is not permitted during Q entry. In general, a system command entered during Q input is executed, but the system's response to the command is not treated as a response to D- After execution of a command, valid input is again awaited (unless the command was one which replaced the contents of the active workspace) . An empty input (one containing nothing other than zero or more spaces) is rejected and the system again awaits input. INTERRUPTING EVALUATED INPUT Execution of a defined function containing a request for Q input can be interrupted at the statement containing the D by entering a statement which has no value (for example <t ' ' or a branch statement, or any defined function which does not return a result) . This suspends execution of the statement containing the U, with the report VALUE ERROR. A command that requires saving the workspace (either SAVE or CONTINUE, described in Section 8), issued during a request for □ input, also interrupts the statement containing the Q before carrying out the command . The response ■+ entered in response to a Q abandons execution of the function and any pendent functions leading up to it. CHARACTER INPUT The quote-quad symbol H (that is-, a quad overstruck with a quote) is a request for character input: entry is permitted at the left margin and data entered are accepted as characters. For example: X-s-B CAN'T (Quote-quad input, not indented) X CAN'T INTERRUPTING CHARACTER INPUT Request for B input can be interrupted,, in the case of certain typewriter terminals, by entering the three letters OUT, in that order, but with a backspace between each pair so that they all overstrike. This interrupts execution, but does not cause an exit from a defined function. Section 7: Function Execution 71 NORMAL OUTPUT The quad symbol appearing immediately to the left of a specification arrow indicates that the value of the expression to the right of the arrow is to be displayed in the standard format (subject to the printing precision DPP and the printing width QPW) . Hence, Q+x is equivalent to the statement X. The longer form Q+x is useful when employing multiple specification. For example, U+Q+X*2 assigns to Q the value X*2 and then prints the value of J* 2. The maximum length of a line of normal display (measured in characters) is called the printing width , and is given by the value of the system variable QPW. The maximum and minimum effective values of the printing width depend upon the system being used, and the appropriate user's guide should be consulted. A display whose lines exceed the printing width is ended at or before the maximum length, and continued on subsequent lines. BARE OUTPUT Normal output includes a concluding new line signal so that the succeeding display (either input or output) will begin at a standard position on the following line. Bare output, denoted by expressions of the form Ch-X does not include this signal if it is followed either by another bare output or by character input (of the form X+B) . Character input following a bare output is treated as though the user had spaced over to the position occupied at the conclusion of the bare output, so that the characters received in response will normally be prefixed by a number of space characters. This allows for the possibility that, after the keyboard is unlocked, the user backspaces into the area occupied by the preceding output. The following function prompts the user with whatever message is supplied as its argument, and evaluates the response: UCR' PROMPT* Z+-PROMPT MSG B+-MSG Z-HD Using such a function, the expression: PROMPT 'ENTER CAPITAL: • would have the following effect: displayed by system ENTER CAPITAL: "lOOO entered by user The value of Z is as many blank characters as there are characters in MSG, followed by the characters entered by the user. In this case Z will have fifteen blanks followed by the character '1000'. The new line signals that would be supplied by the system in order to break lines that exceed the printing width are not supplied with bare output. However, since an expression of the form E+X entered directly from the keyboard (rather than being executed as part of a defined function) must necessarily be followed by another keyboard' entry, the output it causes is concluded with a new line signal. The effect is in this case indistinguishable from normal output, except for the possibility of exceeding the printing width limitation. 72 APL Language SECTION 8: SYSTEM COMMANDS An APL system recognizes two broad classes of instructions, statements and system commands . System commands control the initiation and termination of a work session, saving and reactivating copies of a workspace, and transferring data from one workspace to another. System commands can be invoked only by individual entries from the keyboard and cannot be executed dynamically as part of a defined function. They are prefixed by a right parenthesis. They will be The system commands are summarized in Figure 8.1 discussed under three main headings: 1. The active workspace. a. Action. b. Inquiry. 2. Workspace storage and retrieval. a. Action. b. Inquiry. 3. Access to the system. A command that is not recognizable, or is improperly formed, is rejected with the report INCORRECT COMMAND. Certain commands may also result in more specific trouble reports; these are discussed in the appropriate context and are summarized in Figure 8.2. Once its execution has started, a system command cannot be interrupted, although display of the system's response to the command can be suppressed by an interrupt signal. In the text that follows, each system command is shown in a sample form. In use, the appropriate names or numbers should, of course, be substituted for those shown. A N USERNO LIBNO WSNAME GRPNAME OB J NAME PASS WD NEWPASS [ ] A letter of the alphabet. A number. A user account number. A library number (that is, either a user account number or a public library number) . A workspace name. A group name. A name of an object within a workspace (that is, a function, a variable, or a group) . A password, which must match the previously set value. A new password, which need not match the previously set value. Items enclosed in brackets may in some circumstances be omitted. Section 8: System Commands 73 FORM PURPOSE NORMAL RESPONSE TROUBLE REPORTS TERMINAL CONTROL COMMANDS )number [pass] Identify user and start use of APL [public-adc header system Iress] 1 5 12 13 14 [SAVED time date] ^CONTINUE [newpass] Replace ws CONTINUE by copy of active ws and end use of APL [time date header account CONTINUE] 4 1t ) CONTINUE HOLD [newpass] Replace ws CONTINUE by copy of active ws, end use of APL, but hold connection [time date header account CONTINUE] 4 M )OFF [newpass] End use of APL header account header 4 )OFF HOLD [newpass] End use of APL, but hold connection 4 account ACTIVE WORKSPACE CONTROL COMMANDS ) CLEAR Activate a clear ws CLEAR WS 4 )COPY wsid [pass] Copy all global objects from named ws into active ws SAVED time date 2 3 4 16 17 18 19 20 )COPY wsid [pass] names Copy global objects named from designated ws into active ws SAVED time date 2 3 4 7 16 17 18 19 20 ) ERASE [names]. Erase global objects named from active ws 4 7 16 ) GROUP names Gather objects into (or disperse) a group (first name designates group) 4 8 17 18 )LOAD wsid [pass] Activate copy of named ws SAVED time date 3 4 18 19 )PCOPY wsid [pass] Copy all objects from designated ws not named in active ws SAVED time date 2 3 4 6 16 17 18 19 20 )PCOPY wsid [pass] names Copy objects designated that are not named in active ws SAVED time date 2 3 4 « 7 16 17 18 19 20 ) SYMBOLS number Change maximum number of symbols in ws to number WAS number 4 )WSID wsid [newpass] Change identification of active ws WAS wsid 4 LIBRARY CONTROL COMMANDS )DROP wsid Drop ws from library time date 3 4 20 )SAVE Place copy of active ws in library time date wsid 3 4 9 10 11 18 )SAVE wsid [newpass] Replace named ws by copy of active ws time date 3 4 9 10 11 18 INQUIRY COMMANDS ) FNS [alphabetic] List defined functions (whose initials follow given character in alphabet) [names] 4 )GRP name List members of named group [names] 4 V )GRPS [alphabetic] List groups (whose initials follow given character of alphabet) [names] 4 )LIB [number] [alphabetic] List workspaces in designated library (whose Initials follow given character in alphabet) [names] 3 4 )SI List halted functions state-indicator 4 )3IV List halted functions and associated local state-indicator and 4 names names ) SYMBOLS Give maximum number of names in ws IS number 4 )VARS [alphabetic! List global variables (whose initials follow given character in alphabet) [names] 4 )WSID Give wsid of active ws [number] name 4 Notes: 1. Items in brack* sts are optional 2. Abbreviations < snd meanings: ws \ 7orkspace pass < s colon possibly followed by a password newpass < i pass that does not have to match a previous p as sword header t i port number, time of day, date, and user-code account < < rives the connect time and compute time since 1 ind since beginning of the accounting period ast start wsid < i ws name possibly preceded by a library number public-address a message to users of the system 3. The commands )l IRASEt )FNS. and )VARS have variants that are s ystem functions (see Qgx and Qj ?C) . Figure 8.1: System Commands 74 APL Language No. TROUBLE REPORT 1 ALREADY SIGNED ON 2 DEFN ERROR 3 IMPROPER LIBRARY REFERENCE <* INCORRECT COMMAND 5 INCORRECT SIGN -ON 6 NOT COPIED: names 7 NOT FOUND : purported names 8 NOT GROUPED. NAME IN USE 9 NOT SAVED, THIS WS IS CLEAR 10 NOT SAVED, THIS US IS wsid 11 NOT SAVED, WS QUOTA USED UP 12 NUMBER IN USE 13 NUMBER LOCKED OUT 14 NUMBER NOT IN SYSTEM 15 RESEND 16 SI DAMAGE 17 SYMBOL TABLE FULL 18 WS FULL 19 WS LOCKED 20 WS NOT FOUND Meaning WS APL already in use at terminal Attempted copy or protected copy of function definition as response to □ input request (on some systems) 1) Number is not a library number, or 2) Attempted save into alien library, or 3) Attempted reference to alien CONTINUE WS Global homonyms in active ws are protected Ws does not contain global objects with purported names First name is name of a global function or variab.le A clear ws has no name and cannot be stored Attempted replacement of a stored ws whose identification does not match that of the active ws Allotted number of stored wss previously reached Authorization for use of number has been withdrawn 1) Number entered is not an account number, or 2) Password missing, or 3) Wrong password used Transmission failure or more than the implementation allowed number of characters entered in one line State indicator damaged while performing an ) ERASE or )C0PY command Too many names used Remedy 1) To display account number, use OAI 2) To change account number, execute )0FF HOLD or ) CONTINUE HOLD and sign on Workspace full, possibly because of 1 ) Temporary values produced during evaluation of an expression, or 2) Value assigned to shared variable by partner. 1) Password missing, or 2) Wrong password used No stored ws with given identification 1) Use different name for group, or 2) Erase global object if not needed Remove active ws, then store 1 ) Drop an unneeded ws , or 2) Ask APL operator to increase quota Consult APL operator Consult APL operator Consult APL operator If chronic, redial or have terminal or phone repaired Erase objects not needed, save ws, clear active ws, and perhaps change limit, using )SYMB0LS, copy the saved ws and rename the active ws 1) Erase objects not needed, or 2) Clear state indicator, or 3) Revise method of calculation Figure 8.2: Trouble Reports Section 8: System Commands 75 Items enclosed in angles may in some circumstances be omitted, and, where omitted, the system supplies values from the existing user identification, workspace identification, or previously established password. COMMANDS THAT MODIFY THE WORKSPACE ENVIRONMENT The following system commands affect the active workspace, the environment in which computation takes place and in which names have meaning. In particular, the active workspace contains the settings of the state indicator (discussed in Section 7) and other elements of the computing environment, mediated by several of the system variables (discussed in Section 4) . ) CLEAR This command is used to make a fresh start, discarding the contents of the active workspace, and resetting the environment to standard initial values (see Figure 8.3). At sign-on, the user receives a clear workspace characterized by these same, initial values, unless the workspace CONTINUE was automatically loaded. Symbol table size Index origin, 010 Latent expression, QLX Line counter, QLC State indicator Workspace name Workspace password Printing precision, DPP Printing width, UPW Comparison tolerance, OCT Random link, ORL Work area available, QWA * 256- 1 Empty Empty Cleared None (CLEAR WS) None * 10 * 120 * 1E~13 * 16807 * Depends on the local installation, and, in some systems , upon options selected by the user. * Items marked with an asterisk have values which may vary from system to system. The values shown are widely used. Figure 8.3. Environment Within a Clear Workspace 76 APL Language ) SYMBOLS N Sets the size of the symbol table, that is, the maximum number of names that may occur in the workspace. (Note that the occurrence of a name includes not only the names of functions, variables, or groups themselves, but also any names occurring within their definitions) . New values of the maximum may be set only in a clear workspace. An attempt to change the maximum once the workspace is no longer clear, or to set it outside the range permitted by the system, is rejected with the report INCORRECT COMMAND. Valid use of the command results in the report WAS . . . , showing the former limit. )ERASE 10BJNAME1 0BJNAME2 0BJNAME3 ...] The global objects named are expunged from the workspace; shared variable offers with respect to any of them are retracted. If a name is the name of a group (see below) , the group and all of its members present in the workspace are erased. (If a member of a group is itself a group, xts definition is erased but not its members.) If a halted function is erased, the report SI DAMAGE is displayed, and the name of that function is replaced in the state indicator by blanks. It is not possible to resume the execution of an erased function, and the user should enter ■*■ one or more times to clear the state indicator of indications of damage. If an object named in the command cannot be found, the report NOT FOUND: is emitted, followed by a list of the objects not found . )COPY <LIBNO> WSNAME l-.PASSWDl < OBJNAME 1 ] L0BJNAME2 ...] > The indicated global objects (but not system variables) are copied from the indicated workspace (the source workspace) into the active workspace. The system reports the date and time at which the source workspace was saved. If the list of objects to be copied is omitted, all global objects' other than system variables are copied from the source workspace. If the indicated source workspace is for some reason unavailable, copying cannot take place. The possible errors in gaining access are the same as those discussed under the LOAD command, namely IMPROPER LIBRARY REFERENCE, WS NOT FOUND, WS LOCKED. When an object to be copied is a group, the group membership list is copied as well as all those of its members which exist as global objects in the source workspace. When an object to be copied has the same name as a global object in the active workspace, the copied object replaces it. If there was a shared variable offer with respect to the variable thus replaced, the offer is retracted. If names explicitly mentioned in the copy command are not the names of global objects in the source workspace, the system reports NOT FOUND: followed by a list of the objects not found . Section 8: System Commands 77 Copy During Evaluated Input . A copy command can be entered while a request for evaluated input (□:) is pending. The objects copied will then exist in the workspace but do not become the value of D . The request for evaluated input is then repeated. However, definition mode may not be entered during evaluated input, and hence the definition of a function may not be copied during evaluated input. An attempt to do so is rejected with the report DEFN ERROR. The following trouble reports may arise during copying: WS FULL There is insufficient space to accommodate all the material to be copied. However, those objects copied before space was exhausted remain in the active workspace. SYMBOL TABLE FULL New names occurring in the copied material exhaust the capacity of the symbol table. Those objects copied before the symbol table was exhausted remain in the active workspace. SI DAMAGE A copied object has replaced the definition of a halted function, so that its halted execution cannot be resumed. The user should then enter -*■ enough times to clear the state indicator of indications of damage. )PCOPY <LIBNO> WSNAME L-.PASSWDl < OBJNAME L0BJNAME2 ...] > The protecting copy command works in the same way as the unprotecting copy, described above, except that a global object having the same name as one already present in the active workspace is not copied. If any object is not copied for this reason, the system reports NOT COPIED: followed by a list of the objects not copied. -GROUPING TO FACILITATE COPYING OR ERASURE It is frequently convenient to copy into the active workspace several related functions and variables, and to erase them when they are no longer needed. To facilitate such transfers, a group may be defined by supplying a list of names that are to be copied or erased together. Since the group's definition will exist in the workspace, it must have a name distinct from that of any global object in the workspace. The definition of a group consists of a list of names. It is not necessary that objects having those names exist in the workspace. When a copy command or an erase command mentions the name of a group, then not only the definition of that group but also all global objects whose names appear in the membership list are copied (or erased, as the case may be) . If the membership of a group A includes the name B of another group, the act of copying A causes the membership list of B to be copied, but copying does not extend further. That is, the objects referred to in the membership list of B are not copied. The same applies to erasure. If an object named in the membership list of a group does not exist in the workspace, it cannot be copied or erased, but no report is generated. )GROUP GRPNAME LGRPNAME1 L0BJNAME1 0BJNAME2 ...] A group having the name GRPNAME and consisting of the membership list shown is formed in the active workspace. If 78 APL Language the name is already in use as the name of a group, the new membership list (possibly empty) supersedes the old. If a group is given an empty membership list, it is dispersed . Dispersal of a group has no effects on its members (whereas the command ) ERASE GRPNAME applied to a group expunges both the group definition and the members) . If the name of the group appears also as one of the members of the group, the former membership list is merged with the list provided in the command, thereby appending new names to the membership list. The system makes no acknowledgment of a successful grouping. An attempt to form a group having a name already in use as the name of a global variable or function in the workspace is rejected with the report NOT GROUPED, NAME IN USE. Since the membership list of a group requires space within the workspace, the attempt to form a group may find insufficient space in the workspace or in the symbol table, resulting in the trouble reports WS FULL or SYMBOL TABLE FULL. COMMANDS THAT MONITOR THE ACTIVE WORKSPACE The following commands report aspects of the workspace environment, but produce no change in it. ) SYMBOLS )FNS U] Elicits the report IS ... showing the current maximum number of symbols. Reports a list of the global functions in the active workspace, in alphabetical order [starting with the letter indicated] . )VARS U] )GRPS [A] Reports a list of the global variables in the active workspace, in alphabetical order [starting with the letter indicated] . Reports a list of the groups in the active workspace, in alphabetical order [starting with the letter indicated] . )GRP GRPNAME Reports the membership of the group named GRPNAME. )SI Displays the state indicator, showing the status of halted functions, with the most recently halted first. The list Section 8: System Commands 79 shows the name of the function and the number of the statement at which work is halted. The actions that a user can take with respect to a halted function are described in Section 7. Suspended functions are marked in the state indicator by an asterisk, while pendent functions appear on the state indicator list without an asterisk. The names of functions whose definitions have been damaged (by editing, copying, or erasing them while they are halted) are replaced by blanks in the state indicator. )SIV Displays the state indicator in the same way as )SI , but in addition, with each function listed, lists names that are local to its execution. COMMANDS FOR WORKSPACE STORAGE AND RETRIEVAL The user may request that a duplicate of the currently active workspace be saved for later use. When a duplicate of a saved workspace is subsequently re-activated, the entire environment of computation is restored as it was, except that variables which were shared in the active workspace are not automatically shared again when the workspace is reactivated. LIBRARIES OF SAVED WORKSPACES The set of workspaces saved for a particular user is called that user's library . Each workspace is identified by the user's account number and the name the user assigns to it. However, in referring to workspaces in one's own library, the account number may be omitted; the user's own number is supplied automatically. In systems with multiple users, it is often convenient to use functions or variables contributed by others. One user may activate an entire workspace saved by another user, or may copy from it selected items. To do so both the library number and the name of the desired workspace must be supplied. However, the system provides no way of learning either the account numbers or the names of workspaces belonging to other users. Thus a user may make use of material from the libraries of others only if they supply that information. In no case may a user add, change, or delete material from the library of another user. Certain libraries (usually identified by a particular group of library numbers) are not assigned to individual users, but are designated as public libraries. Any user may obtain a list of workspaces in a public library, and may use public workspaces. However, there may be restrictions on who can save, drop, or modify a workspace in a public library. In general, a public workspace can be re~saved or deleted only by the user who first saved it. NAMES AND PASSWORDS FOR WORKSPACES A saved workspace must be named. The name of a workspace may duplicate a name used for an APL object within the workspace. A password may be paired with the name of a workspace. Once this is done, any reference to the saved workspace (other than dropping it) must be accompanied by the password. 80 APL Language The rules governing what workspace names are permissible and what passwords are permissible may differ from each other and from the rules governing names within a workspace. In particular, the number of significant characters in a workspace name or in a password may differ, and may be less than the number of significant characters in a name used within a workspace. Workspace names and passwords may be composed of alphabetic and numeric characters, but not spaces or special symbols; workspace names must begin with an alphabetic, but this restriction does not apply to passwords. )WSID <LIBNO> WSNAME l-.NEWPASS] Assigns to the active workspace the name indicated, and (optionally) the library number or the password indicated. Use of the colon with nothing following it assigns an empty password; that is, it removes a former password if there was one. If the active workspace is subsequently saved, future use of the saved workspace will require use of the password set here. Setting of the active workspace's identif cation is acknowledged by the report WAS . . . followed by the former name, but not the former password. )SAVE < <LIBNO> WSNAME <:NEWPASS> > A duplicate of the active workspace is saved (optionally, in the indicated public library, otherwise in the user's own library) under the indicated name, and (optionally) with the new password indicated. If the user number, workspace name, or password are omitted, they are supplied from the workspace identification. After saving, the active workspace has the same indentif ication (including account number, name, and password) as the saved workspace. Although saving does not affect the state of sharing in the active workspace, current values of the shared variables are saved in the stored copy. Saving is acknowledged by a report showing the date and time at which the workspace was saved. The command to save the active workspace may be rejected, with trouble reports as follows: IMPROPER LIBRARY REFERENCE The system does not permit a workspace to be saved in the private library of another user, or in a non-existent public- library, nor does it permit a workspace named CONTINUE to be saved in a public library. NOT SAVED, THIS WS IS ... Saving is not permitted when the name given in the command matches the identification of an existing saved workspace but does not match the identification of the active workspace. This restriction prevents the user from inadvertently overwriting one workspace with another. WS QUOTA USED UP Saving is permitted only while the number of workspaces currently saved or the space used by the saved workspaces is less than the user's allocation. Quotas are set by the system operator. WS FULL The workspace contains a shared variable whose value, when brought in to the workspace, would require for its storage more work area than is available in the workspace. Section 8: System Commands 81 NO SPACE There is insufficient space in the system's auxiliary storage to accomodate the workspace. LIBRARY TABLE FULL The system's directory of saved workspaces lacks space in which to record this one. The last two problems cannot be remedied by the user's action but require intervention from the system manager to expand the system facilities. ) CONTINUE WOLD] <:NEWPASS> The active workspace is saved under the name CONTINUE , and (unless a different password is specified) with the password previously assigned to the active workspace. Then the terminal is signed off in the same way as with the command )OFF, described below. Unless the CONTINUE workspace is password-protected, it will be automatically loaded at the next sign-on. The system operator has the power to force a sign off ("bounce") some or all users. If a user is bounced, the system behaves as though the user had entered the command ) CONTINUE. A ) CONTINUE is also executed automatically if the user's connection to the system is broken without a normal sign-off; see the discussion of "Automatic Saving After Line Drop," below. The command )CONTINUE may be rejected for the same reasons that apply to )SAVE , listed above. )L0AD <LIBNO> WSNAME L-.PASSWD] A duplicate of the indicated workspace (including its entire computing environment) becomes the user's active workspace. Shared variable offers in the former active workspace are retracted. Following a successful )LOAD, the system reports the date and time at which the loaded workspace was last saved. The system then immediately executes the latent expression {OLX) . Invalid requests to load a workspace may result in the following trouble reports: WS NOT FOUND The indicated workspace cannot be found. WS LOCKED The password supplied in the command does not match the password of the saved workspace, or is missing from the command when required. IMPROPER LIBRARY REFERENCE The user is ineligible to use the indicated library. )DROP <LIBNO> WSNAME The named workspace is removed from the user's library or from the indicated public library. The system reports the date and time. _ The password is not required to drop a saved workspace. Dropping a workspace has no effect on the active workspace. 82 APL Language An attempt to drop a workspace saved by someone other than the user is rejected with the report IMPROPER LIBRARY REFERENCE . Reference to a non-existent workspace is rejected with the report WS NOT FOUND- AUTOMATIC SAVING AFTER LINE-DROP AND SPECIAL PROPERTIES OF THE CONTINUE WORKSPACE If the connection to the computer or host system is broken before a normal sign off, and the active workspace is not empty, the system acts as though the user had entered the command )CONTINUE , thereby saving the contents of the active workspace under the name CONTINUE - The CONTINUE workspace is intended solely for temporary storage. Regardless of the name of the active workspace, it can under these conditions be saved under the name CONTINUE- That is, a previously saved workspace named CONTINUE may be replaced by the active workspace without the protection against overwriting provided for other workspaces. Since any account may have a workspace named CONTINUE, to assure privacy the CONTINUE workspace of one user can not be loaded by another user, nor can it be saved in a public library. The workspace CONTINUE does not count as part of the user's quota of saved workspaces. COMMANDS REGARDING WORKSPACE STORAGE AND RETRIEVAL )WSID Reports the identification of the active workspace, showing the library number if other than the user's own, and the workspace name, but not the password. )LIB <LIBNO> [4] Displays the names of the workspaces in the user's private library or in the indicated public library. In systems in which the optional letter of the alphabet can be used the display is alphabetized. If the command is followed by a letter of the alphabet, the display begins with names starting with that letter. An attempt to display the list of workspaces in another user's private library or in a non-existent public library is rejected with the report IM-PROPER LIBRARY REFERENCE- ACCESS TO THE SYSTEM Each user of the system is assigned by the system manager an account identification used to identify data storage and charges for use of the system. The account identification is required in order to sign on. Each user is also assigned a quota indicating the maximum _ number or capacity of saved workspaces, and an interface quota indicating the maximum number of variables that may be shared simultaneously. The system manager may also establish a cpu limit for an account, limiting the amount of central processor time per keyboard entry. _ When the limit is reached, an interruption is made in the same way as if a strong interrupt had been signalled from the keyboard. Section 8: System Commands 83 SIGN ON Before work can be started, a physical connection to the computer must first be established. This may require as little as turning a switch, or may require establishing a link from a dial-up terminal to a central computer, possibly passing through intermediary computing systems which are host to APL, depending on the system employed and the type of terminal device employed. Once communication is established, a numerical identification of the user must be provided to the system. The precise manner of providing this varies from system to system. At sign on, either a clear workspace or the CONTINUE workspace is activated, depending on the condition which terminated the preceding session, and the system in use. Successful sign on is acknowledged by a message showing the port number, the date and time, the user's name, and the system identification. This may be preceded by a broadcast message from the system operator. If CONTINUE was activated, the system reports the date and time at which it was saved. An attempt to sign on may be rejected, with one of the following reports: ALREADY SIGNED ON The terminal is in use, and must first be signed off (or bounced by the system operator) before a new sign-on can be accepted. NUMBER IN USE The indicated account number is in use at another port. This may arise either because another user is in fact using the account, or occasionally (perhaps because of an equipment problem) because the system did not complete disconnection at an earlier work session. NUMBER NOT IN SYSTEM This report means either that the indicated account has not been enrolled, or that the password supplied does not match the password last set. NUMBER LOCKED OUT Authorization for use of the account has been withdrawn. Workspaces saved in this library cannot be loaded or copied by anyone. SIGN OFF )OFF I HOLD] <:NEWPASS> An accounting report is displayed, showing the port number, date and time, and user code, followed by the connect time and central processor time used at the current session and cumulatively since the last accounting. If the word HOLD is used, the connection to the computer or host system is held for a brief period to accommodate sign on by another user. If a colon is used, the word following it (or none) will be the password for subsequent sign ons. 84 APL Language )CONTINUE IH0LD~] <:NEWPASS> Because this command has the dual effects of saving the active workspace and signing the user off, it is described here and also in the section on workspace storage and retrieval. The user is signed off in the same manner as with )OFF, but the active workspace is first saved under the name CONTINUE. If a password is set, it will apply at subsequent sign-ons. The command may be rejected if it is impossible to save the CONTINUE workspace, either because the physical resources of the system are unable to accomodate it, or because of a full workspace produced when the value of a shared variable is transferred to the workspace. See the preceding discussion of the commands )SAVE and ) CONTINUE. Section 8: System Commands 85 INDEX 1050 terminal, 51. absolute value, 20. access, to APL system, 73. access control for shared variable, 52 53 55 57. access functions, isolation of, as programming technique, 4. access state of shared variable, 55. account identification, 16 50 83. account information, 51 . activation, workspace, and execution of latent expression, 50 82. activation, workspace, by load command, 2 50 51 82. active workspace, 2 15 50 51 73 79 82. active workspace, system commands that affect, 73 79 82. adding statement, to function definition, 63. adding to statement, in function definition, 64. addition, 12 18 19. alpha , 12. alphabetic characters, 10 12. ALREADY SIGNED ON, 75 84. alternating sum, 25. alternating product, 26. and, logical, 12 18 20. announcement from system operator, received at sign on, 84. application package, workspace for, 2 6. arccos, 18 24. arcosh, 18 24. arcsin, 18 24. arctan, 14 18 24. argument, of a function, 13 66. arguments, number of. See valence, array, as primitive object, 7 14 17. arsinh, 18. artanh, 18. atomic vector, 50 51. attention key, as interrupt signal, 10. automatic start of function execution upon load, 51. availability, of name, 49 60. axis, operator, 7 27 33 37. B backspace, 9 10 71. bar, 12. bare output, 72. base, 12. base null, 12. base-value, 42. BCD terminal, 51 . billing, system for, 2 6. binomial, 18 19 24 25. blank, as separator, 13. blank, in character constants, 13. body of a function, 7 59. boolean functions, 17 21. bounce, 82. bracket, 12. branch, control of sequence, 7 9 61 . canonical representation, 47 48 59 65. cap, 12. cap null, 12. card reader, communication through shared variables, 52. caret, to mark point at which correction was requested, 10. carrier return, omitted in bare output, 72. carrier return, to release entry statement, 9. catenate, 30. catenate, conformability requirements, 34. ceiling, 18 21. chaining, to join arrays. See catenate, laminate, character display, see format, character editing, of statements in function definition, 64. CHARACTER ERROR, 11. character input, 70. character input , interrupted , 71. character set, 10 12. character representation, function, 47 48 59 65. character representation, numbers, 44. characteristics of APL, 4. characteristic vector, 30 39. characters, enterable from terminal , 9 . circle, 12 19. circle bar, 12. circle slope, 12. circle stile, 12. circular functions, 18 23. classification, names, 49. CLEAR, command, 74. clear workspace, 50 76. CLEAR WS, 50 76. Index 87 close shoe, 12. colon, 12 62. column, 27 41 . combinations, 18 19 24 25. comma, 12 33. comment, 62. communication, with processors external to APL, 7 52. comparison tolerance, 20 22 50 51 76. complement, logical, 20. complex roots, undefined, 22. composite character, 10. compound expression, 14. compound interest, example, 1. compress, 30 36. compute time, 51. concurrent process, and shared variables, 52. conformability, 11 17 28 34. conjugate, 18. 20. connect time, 51 . connection, broken, 82 83. connection, establishing, 84. connection, hold, 74 82 84. constant, 10. continuation, output line that exceeds printing width, 72. CONTINUE, command, 74. 82 83. CONTINUE, workspace, 80 84. CONTINUE HOLD, command, 74 80 83. coordinate, array, 4 27 37. COPY, command, 71 74 77 78. copying, of function definition, 59 71 77. correction of statement being entered , 9 . correction, of entry before release, 9. cos, 18 23. cosh, 18 23. coupling, degree of, 54 57. cup , 12. cursor, to indicate position of next entry, 9. D data, names used for, 1. data transformations, 43. date, 50 51. deal, 18 30 39. decimal point, in display, 45. decimal point, in entering numbers , 10. decode, 30 42. defined functions, control of sequence of execution in, 9 61 defined functions, treated same Wciy as primitives, 7 66. definition error, 11 71. DEFN ERROR, 11 71 75 77 degree of coupling, 54. del, 12. del stile, 12. del tilde, 12. delay, 48 50. deleting a statement, of function definition, 63. deletion, workspace. See drop, delta, 12. delta stile, 12. DESCRIBE, variable used to explain an application package, 2. determinant, function for, as example, 65. device, used to display computer's response, 1 . diagonal, 35. dieresis, 12. dimension, see shape or axis, disk-file, used in conjunction with APL, 1 . display, of function definition, 63. display, of result of computation, 1 9. distinguished names, 47. division, 12 18 19. division by zero, 17. domain, of scalar functions, 17. DOMAIN ERROR, 11. domain error, produced by locked function, 69. domino , 12 40. dot, 12. double attention, as strong interrupt, 10. down arrow , 12. downstile, character, 10 12. drop, 30 36. DROP, command, 74. dyadic, valence of function, 13. dyadic and mondaic forms of primitive functions, 18. dyadic functions, identity elements of, 19. E e, base of natural logarithm, 22. editing, of function definition, 59 63 64. editing, of function header, 63 64. empty array, 32. empty array, reduction over, 17 26. empty branch, 62. encode, 30 42. entry, from keyboard, 1 7 9 70 71 environment of computation, 47. epsilon, 12. equal, 12 18 19. ERASE, command, 74 77. erasure, dynamic, 49. error reports, for execute, 43. error report, form of, 10. 88 APL Language error report, table of, 11. error report, when evoked, 10. establishment, of function definition, 59. evaluated input, 70 71. evaluated input, during copy, 78. evaluated input, interrupted, 71. even roots, of negative numbers, undefined, 22. exclusive or, 21 . execute, 30 43. execute, error report, 43. execution, of defined function, 66. execution, order of, 14. execution, sequence of statements in defined function, 61 66. exit, branch to, 62. exit, from function definition mode , 64. expand , 30 36 37. exponentiation, 22. exponential, 18 23. exponential form, see scaled form, expression, 9. expunge, object from workspace, 48. extension of scalar function to array, 17. factorial, 18 24. false, number used to represent, 20. first, selection of by take, 36. first axis, 37. fix, function definition, 47 48 59. floor, 10 18 21 . FNS, command, 2 74 79. format, 30 ; ii Tj * function, defined, used in statement, 1 3 5 66. function, derivation of term, 13. function, establishment, 47. function, represented as character matrix, 6 47. function definition mode, 59 63 64. function display, by canonical representation, 6 65. function display, in definition mode , 6 4. function establishment, 47 48 59. function establishment, failure of, 60. function tables, generated by outer product, 29. functions, list of, 2 74 79. functions, primitive scalar, 18. functions, used in sample application, display of, 4 6. fuzz, see comparison tolerance. general logarithm, 18 23. general offer, of shared variable, 54. global names, as referents of system commands and del, 61. global objects, in erase command, 77. global use of names, 60. grade, 30 38 39. greater than, 12 19. greatest common divisor, 62 69. grid, of consecutive values, 38. group, appending new members, 79. GROUP, command, 74 78. group, dispersal of, 79. group, formation of, 78. group, in erase command, 77. GRP , command , 74 79. GRPS, command, 74 79. H half duplex, shared variable access control, 57. halted execution, of defined function, 60 66 67. header, of a function, 7 59 60. hierarchy, absence of, 14. HOLD, as part of CONTINUE or HOLD commands, 74 82 84. host system, 47. hyperbolic functions, 18 23. identification, of user account, 16 50 83. identity elements, 17 19. implication, 21 . IMPLICIT ERROR, 11 50. IMPROPER LIBRARY REFERENCE, 75 82 83. INCORRECT COMMAND, 73. INCORRECT SIGN ON, 75. INDEX ERROR, 11 . index generator, 30 38. index of, 30 38. index origin, 15 22 37 50 51 76. indexing, of arrays by arrays, 7 30 37. inhibition, of set or use of shared variable, 57. initial value, of shared variable, 54. inner product, conformability of arrays , 28 . inner product, operator, 7 25. input from terminal, 1 70 71 . inserting statement, to function definition, 63. integer part, 21 . Index 89 interface quota, 54. INTERFACE QUOTA EXHAUSTED , 11. interrupt, from terminal, 9. INTERRUPT, system response, 11. interruption, of character input, 71. interruption, of evaluated input, 71. interruption, of pending set or use of a shared variable, 55. interruption, of system command, 73. inventory, system for, 2 4 6. inverse circular functions, 24. inverse permutation, 38. invoice, in sample application, 6. iota, 12 30 38. italic, font used for capital letters, 10. iterative procedures, use of branching in, 61 . I-becim, 12. K key, see password. keyboard, typewriter-like, 1 12. keying time, 51 . labels, in function definition, 62. labels, localization of, 62. large data array, facilitated by generalized access, 4. last axis, 37. last elements, selection of, by take, 36. latent expression, 50 51 76. least squares approximation, in matrix division, 41 . left arrow, 9 12. left identity, 17. LENGTH ERROR, 11 17. less than, 12 18 19. letters of the alphabet, used to form names , 1 . LIB, command, 74. library, collection of workspaces, 15 16 80. library, public and private, 16 80 83. library number, 77. LIBRARY TABLE FULL, trouble rpeort during save, 75 82. line counter, 50 51 76. line drop, automatic saving of continue workspace, 82 83. line zero, of function definition, 62. list of customers, stored as matrix, 3. LOAD, command, 2 15 50 51 73 79 82. load, workspace, and execution of latent expression, 51 73 79 82. local names, in function header, 60. local use of names, 61. local variables, and state indicator, 80. local variables, in function execution, 66. localization, of function arguments and result, 66. localization, of system variables, 50. lock, see password, locked function, 65 69. locked function, interruption of, 69. LOCKED OUT, 84. log, 12 14. logarithm, 19 22. logarithm, absence of general identity element for, 17. logical complement, 20. logical negation, 20. M magnitude, 18 20. material implication, 21. matrix, 14. matrix divide, 30 40. matrix inverse, 30 40. matrix product, generalized as inner product, 7 28. maximum, 18 19 21. membership, 30 39. message from system operator, received at sign on, 84. minimum , 10 18 19 21. minus , 18 19. mixed functions, 17. mixed functions, classification of, 29. monadic, valence of function, 13, monadic and dyadic forms of primitive functions, 18. multiple specification, 9. multiplication, 12 18 19 25. multi-dimensional arrays, 14. N name, expunged from workspace, 48. name, standing for variable, 1 9. name classification, 48 49. name list, 48 49. named functions or data, benefits of using, 2. names, distinguished, 47. names , for symbols , 10. 90 APL Language names, in statements from keyboard, 1 . names, rules for forming, 16 80. nand, 12 18. natural logarithm, 18 22 23. negative, 18 20. negative numbers, sign used for, 13. new-line signal, omitted from bare output, 72. niladic, valence of function, 13. NO SHARES, system response, 11. NO SPACE, 82. nor, 12 18. not, logical, 18 20. NOT COPIED, 75 78. not equal, 12 18 19. NOT FOUND, 75 77. not greater than, 12 18 19. NOT GROUPED, 75 79. not less than, 12 18 19. NOT SAVED, 75 81 . notebook, similiarity to workspace, 2. null, 12. NUMBER IN USE, 75 84. NUMBER LOCKED OUT, 75 84. NUMBER NOT IN SYSTEM, 75 84. numbers, group of used together, 1. numbers , in statements entered from keyboard , 1 . numeric, characters, 10. numerical functions, 29 40. OFF, command, 74. OFF HOLD, command, 74. offer, shared variable, 50 52 54. omega , 12. one-origin indexing, 15. open shoe, 12. operators, which modify primitive functions, 7 13 17 25. or, logical, 12 18 20. order, of elements in reshaping an array, 32. order of execution, 14. orders, customer, in sample application, 4 6. origin, index, 15 22 37 50 51 76. out of, combinations, or binomial coefficients, 18 19 24 25. outer product, operator, 7 29. overbar, for negative numbers, 12 13. overstrike, illegitimate, 11. overstriking, to form escape character from character input, 71. parentheses, 12. parentheses, used to indicate order of execution, 14. password, for user identification, 16 73 84. password, for workspace, 16 76 77 80 82. password, in system commands, 73 82. PCOPY, command, 74 78. pendent execution, 67. pendent function, and localization of names, 61 . pendent functions, and state indicator, 67. permutation, 38. permutation, random, 39. pi, 23. pi times, 18 23. plus, 12 18 19. polynomial evaluation, see decode, power, 18 19 22 25. precedence, absence of, for functions, 7 14. precision, and comparison tolerance, 20. precision, of character representation , 44. primitive scalar functions, 18. primitive objects, arrays as, 4 14. primitive functions, classification of, 17. primitive objects, numbers and symbols as, 1 . primitive functions, symbols for, 8 10. printer, used in conjunction with APL, 1 52. printing precision, 50 51 72 76. printing width, 51. printing width, and bare output, 72. printing width, in function definition, 50. printing width, in normal output, 72 76. private library, 16. processor, communicating with APL via shared variables, 52. program, sequence of statements, 1 6 61. projection, on space spanned by column vectors, obtained from matrix division, 41. prompt, by use of bare output, 72. prompting message, before request for input, 6. protecting copy, 74 78. pseudo-random numbers, 22 39. public library, 16 80 81 83. punch cards, use in conjunction with APL, 52. Index 91 Pythagorean functions, 18 23, Q quad , 12. quad input, 70 71 . quad- prime input, 70. query, 12. quota, of cpu time per entry, 83. quota, of saved workspaces, 80 83. quota, of shared variables, 54 83. quote, 12. quote dot, 12. quote marks, around character constants, 13. quote mark, as member of character vector , 13. quote quad, 12 70. reversing half duplex, shared variable access control, 57. revision, of entry before release, 9. revision, of function definition, 59 63 64. rho, 12. rho, reshape, 32. rho, to determine shape of array, 15. right arrow, 12 61. right identity, 17. roll, 18 22. root, square, etc., 22. rotate, 30 33. rotation, 33. row, 27. R radian measure, in argument to sin, cos, tan, 23. radix, 42. random link, 22 50 51 76. random number generator, 22. random permutation, 39. random selection without replacement, 39. rank, of an array, 14 32. rank, of result produced by indexing, 38. rank, restrictions on, for arguments of mixed functions, 31 . RANK ERROR, 11 . rank order, 39. rank vector, 32. ravel, 30 31. real numbers, functions on, 17. reciprocal, 18 20. recursion, 69. reduction, operator, 7 25. reduction over empty array, 17^25. relations, 18 20. remainder, 19. replace statement, in function definition, 63. representation, see encode and format . RESEND, system response, 11. reshape, 30 31 . residue, 18 19. residue, in definition of encode, 42. response, to statements entered from keyboard , 1 . result, of defined function, 66. retraction, of shared variable offer, 57. return, to release statement being entered, 9. reverse, 30 33. sales, system for, 2 6. SAVE, command, 74 80. scalar, as argument of inner product, 29. scalar, constant, 10. scalar, for vector in catenate, 34. scalar functions, concept, 17. scalar functions, primitive, list of, 18. scalar in place of vector, for mixed functions, 31. scaled form, numbers represented by, 10. scan, operator, 7 25 26. selection, functions for, 29 36. selector generator, 38. Selectric terminal, 51. semantic rules , independent of data representation, 7. semicolon, 12 37. sequence of control, 1 7 61. set membership, 39. setting shared variable, 52 55. shadowing, of global names by local names, 61 . shape, function, 30 31. shape, of array, 14 15 32. shape vector, 32. shared variable, 50 57. shared variable offer, 52 53. shared variable, and workspace full during save, 80. shared variable, inquiries regarding, 53 57. shared variable, quota, 54. shared variable, retraction of, 53 57. shared variable, shared with the system environment, 50 52. shared variable, to communicate with processors outside APL, 7. SI, command, 11 74 78'. 92 APL Language SI DAMAGE, 11 68 75 78. side effects, absence of, 7. sign off, procedure for, 84. sign on, procedure for, 84. significance, of names, 1. signum, 18 20. simplex, shared variable access control, 57. sin, 14 18 23. singularity, of matrix to be inverted, 40. sinh, 18 23. SIV, command, 7 4 80. size, of array, 3 14. slash, 12. slash bar, 12. slope, 12. slope bar, 12. space , 12. spaces, as separators, 13. special characters, 10. specification, 9. specification, multiple, 9. star, 12. state indicator, 15 67 74 80. state indicator damage, 11 68 75 78. state indicator, clearing, 67 76 79. state indicator, with display of local variables, 74 80. statement, 1 73. statement, entered from keyboard, 1. statement, form of, 9. statement types, listed, 7. stile, 12. stop control, 66 68. storage and retrieval , of workspaces, 73. strong interrupt, 9. structure, functions for, 29. structure, of arrays, 14. subtraction, 13 18. surrogate name, for shared variable, 52 53. suspended execution, 61 67 80. suspended function, and localization of names, 61 67 80. suspended function, and state indicator, 61 67 80. suspended function, automatic restart by latent expression, 50. symbol table, 76 78. SYMBOL TABLE FULL, 11 75. SYMBOLS, command, 74 77 79. symbols, in statements entered from keyboard , 1 . symbols, used to represent primitive functions, 8 10. syntax, 1 7 14 59 60. SYNTAX ERROR, 11. system commands, 16 73 74. SYSTEM ERROR, 11 . system functions, 47 48. system variables, to communicate with APL environment ,71517 47 50. table, as matrix, 14. tables, generated by outer product, 29. table-generating functions, 25. tabular displays, use of format to generate, 46. take, 30 36. tan, 18 23. tanh, 18 23. tapes, communication through shared variable, 1 52. terminal, common characteristics of, 9. terminal, typewriter-like, 9. terminal, video, 9. terminal control characters, obtained from atomic vector, 51. terminal type, 51. text processing, 70. three-dimensional array, example of, 3. tilde, 12. time stamp, 50 51. times, 12 18 19 25. top , 12. top null, 12. trace Control, 68. transformations, numeric to character and vice versa, 29. transpose, general, 30 35. transpose, ordinary, 30 35. trigonometric functions , see circular functions, trouble reports, 75. true, number 1 used to represent, 20. type, data, 16 29 43. type element, non-APL, used for application, 3.' U undefined values from certain expressions, 17. underbar , 12. up arrow, 12. upstile, 12. use of shared variable facility, 52. user identification, 16 50 83. user load, 50 51 . using shared variable, restriction imposed by access control, 55. Index 93 V valence, function, 7 13. VALUE ERROR, 1 1 . variable, named collection of data, 1 . variables, identified by name class function, 49. variables, list of, 2 74 79. VARS, command, 2 74 79. vector , entry of , 10 13 14. W weak interrupt, 9. width, of character representation, 44. work area available, 50 51 76. workspace , active ,2 15. workspace, as unit of storage, 15 16. workspace, prepared, as example, 2. workspace full, 11 57 69 75 78 79 30. workspace name, 73 74 80. WS FULL, 11 57 69 75 78 79 80. WS LOCKED, 75 77 79 82. WS NOT FOUND, 75 77 79 82. WSID, command, 73 74 80. zero divided by zero, defined, 19, zero-origin indexing, 15. 94 APL Language APL Language Reader's GC26-3847-0 Comment Form Your comments about this publication will help us to improve it for you. Comment in the space below, giving specific page and paragraph references whenever possible. All comments become the property of IBM. Please do not use this form to ask technical questions about IBM systems and programs or to request copies of publications. Rather, direct such questions or requests to your local IBM representative. If you would like a reply, please provide your name, job title, and business address (including ZIP code). Fold on two lines, staple, and mail. No postage necessary if mailed in the U.S.A. (Elsewhere, any IBM representative will be happy to forward your comments.) Thank you for your cooperation. GC26-3847-0 Fold and Staple First Class Permit Number 439 Palo Alto, California Business Reply Mail No postage necessary if mailed in the U.S.A. Postage will be paid by: IBM Corporation System Development Division LDF Publishing- Department J04 1501 California Avenue Palo Alto, California 94304 > -a 3 in c CO o ro N5 Q. 5' c in > Fold and Staple O n o> CO 03 mm ® International Business Machines Corporation Data Processing Division 1 133 Westchester Avenue, White Plains, New York 10604 (U.S.A. only! IBM World Trade Corporation 821 United Nations Plaza, New York, New York 10017 (International) GC26-3847-0 > 0) 3 c c/5 CO o 3' r-t- a. C CO > o NO CT> CO 00 •P» -J mm International Business Machines Corporation Date Processing Division 1133 Westchester Avenue, White Plains, New York 10604 (U.S.A. only) IBM World Trade Corporation 821 United Nations Plaza, New York, New York 10017 (International)